Cấu hình nhiều ví dụ về body của yêu cầu

Apidog hỗ trợ cấu hình nhiều ví dụ cho body của yêu cầu thuộc loại JSON, XML, Raw và MsgPack. Tính năng này hữu ích cho:

Cấu hình ví dụ cho các kịch bản nghiệp vụ khác nhau: Ví dụ: yêu cầu thông thường so với yêu cầu ngoại lệ.

Tuân thủ các đặc tả OAS 3.0/3.1: Hỗ trợ xuất các đặc tả OpenAPI tiêu chuẩn.

Chuyển đổi nhanh giữa các ví dụ: Hữu ích trong quá trình gỡ lỗi và kiểm thử tự động.

Cấu hình nhiều ví dụ về body của yêu cầu

Yêu cầu Apidog phiên bản 2.7.0 trở lên.

Tạo ví dụ mới về body của yêu cầu

Truy cập trang Edit của tài liệu endpoint.

Tìm phần Request Body.

Nhấp vào nút + Add để tạo một ví dụ mới về body của yêu cầu.

Cấu hình ví dụ về body của yêu cầu

Example Name (tùy chọn): Nếu để trống, giá trị mặc định sẽ là Example 1, Example 2, v.v.

Example Value (bắt buộc): Cung cấp dữ liệu ví dụ thực tế cho body của yêu cầu.

Description (tùy chọn): Thêm mô tả để giải thích ví dụ. Hỗ trợ định dạng Markdown cho văn bản phong phú.

OAS Key (tùy chọn): Được sử dụng khi xuất đặc tả OpenAPI. Nếu không cung cấp, số thứ tự sẽ được sử dụng thay thế.

OAS Extensions (trường tùy chỉnh): Nếu được cung cấp, giá trị này sẽ được giữ lại trong quá trình xuất.

Lưu và sử dụng ví dụ về body của yêu cầu

Sau khi bạn lưu ví dụ, ví dụ đó sẽ có sẵn để sử dụng. Trong quá trình gỡ lỗi, bạn có thể dễ dàng chọn từ các ví dụ khác nhau để kiểm thử endpoint của mình.

Sử dụng ví dụ về body của yêu cầu trong khi gỡ lỗi

TIP

Đối với body của yêu cầu thuộc loại Raw, chỉ giá trị ví dụ đầu tiên được hiển thị trong quá trình gỡ lỗi.

Trích xuất tham số yêu cầu dưới dạng ví dụ

Trong khi gỡ lỗi, nếu bạn đã cấu hình thủ công body của yêu cầu và muốn lưu nó dưới dạng ví dụ, chỉ cần nhấp: Extract > Extract to "Request Example".

Chọn tùy chọn trích xuất

Bạn sẽ được nhắc chọn cách lưu các tham số yêu cầu:

Overwrite the Example: Thay thế một ví dụ đã lưu trước đó.

New Example: Lưu dưới dạng một ví dụ hoàn toàn mới.

TIP

Theo mặc định, giá trị gỡ lỗi hiện tại sẽ tự động được điền vào ví dụ.

Kịch bản sử dụng

Sử dụng ví dụ về body của yêu cầu trong khi gỡ lỗi

Truy cập trang Run của tài liệu endpoint và tìm phần Auto-generate.

Nhấp vào menu thả xuống để chọn một ví dụ về body của yêu cầu. Ví dụ sẽ được tự động điền.

Chuyển đổi ví dụ về body của yêu cầu trong khi gỡ lỗi

Bạn có thể chuyển đổi giữa các ví dụ theo thời gian thực và gửi yêu cầu với ví dụ đã chọn.

Thiết lập nâng cao

Nhấp vào biểu tượng thả xuống bên cạnh Auto-generate để truy cập các tùy chọn sau:

EXAMPLES: Chọn từ các ví dụ body của yêu cầu đã được định nghĩa sẵn.

Generate Each Time: Tự động tạo các giá trị ngẫu nhiên dựa trên quy tắc mock.

Auto-generation Preference: Để biết thêm các cấu hình nâng cao, hãy tham khảo Tạo yêu cầu.

Hiển thị tài liệu

Đối với một ví dụ body của yêu cầu duy nhất: Hiển thị ở chế độ xem đơn giản hóa mà không hiển thị tên ví dụ.

Đối với nhiều ví dụ body của yêu cầu: Cho phép chuyển đổi giữa các ví dụ trong bố cục song song, hiển thị tên ví dụ và mô tả Markdown.

Thứ tự hiển thị

Thứ tự hiển thị của các ví dụ body của yêu cầu tuân theo mức ưu tiên sau:

Example Name > OAS Key > Số thứ tự (tự động tăng từ 1).

Các mục không rỗng được hiển thị trước.

Tuân thủ OAS

OAS Key

OAS key kiểm soát tên trường của các ví dụ khi xuất đặc tả OpenAPI.

Cấu hình: Điền OAS Key cho các ví dụ body của yêu cầu.

Quy tắc xuất:

Khi đã điền: OAS key được cung cấp sẽ được sử dụng làm tên trường trong đối tượng examples.

Khi chưa điền: Số thứ tự (bắt đầu từ 1) sẽ tự động được sử dụng làm tên trường.

Khi đã điền

Khi chưa điền:

 "examples": {
   "example1": {
      "value": {
        "name": "Blake Keeling",
        "id": "165061",
        "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    },
    "example2": {
       "value": {
        "name": "Jolie Kutch",
        "id": "138164",
        "email": "Jolie_Kutch@hotmail.com"
      },
      "summary": "example 2",
      "description": "This is`example 2`"
    }
  }

"examples": {
   "1": {
     "value": {
       "name": "Blake Keeling",
       "id": "165061",
       "email": "Blake.Keeling@gmail.com"
     },
     "summary": "example1",
     "description": "This is`example 1`"
   },
    "2": {
      "value": {
       "name": "Jolie Kutch",
       "id": "138164",
       "email": "Jolie_Kutch@hotmail.com"
     },
     "summary": "example 2",
     "description": "This is`example 2`"
   }
 }

OAS Extensions

Bạn có thể thêm các phần mở rộng OpenAPI Specification (OAS) tùy chỉnh vào ví dụ.

Cấu hình: Nhập các cặp khóa-giá trị JSON vào trường OAS Extension.

{
  "x-demo": true,
  "x-scenario": "error_case"
}

Hiệu quả khi xuất: Các phần mở rộng OAS tùy chỉnh sẽ được giữ nguyên đầy đủ và được đưa vào đặc tả OpenAPI đã xuất.

"examples": {
    "example1": {
      "x-demo": true,
      "x-scenario": "error_case",
      "value": {
         "name": "Blake Keeling",
         "id": "165061",
         "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    }
}

Câu hỏi thường gặp

Cách bật nhiều ví dụ về body của yêu cầu trong các dự án cũ?

Không cần thao tác thủ công! Khi bạn thêm ví dụ body của yêu cầu thứ hai vào một endpoint hiện có, hệ thống sẽ tự động nâng cấp định dạng để hỗ trợ nhiều ví dụ.

Cách xử lý nhiều ví dụ về body của yêu cầu khi xuất OAS?

Thứ tự của các ví dụ body của yêu cầu có thay đổi trong OAS đã xuất không?

Làm thế nào để tên ví dụ đã xuất thân thiện hơn?

Cấu hình nhiều ví dụ về body của yêu cầu

Cấu hình nhiều ví dụ về body của yêu cầu#

Trích xuất tham số yêu cầu dưới dạng ví dụ#

Kịch bản sử dụng#

Sử dụng ví dụ về body của yêu cầu trong khi gỡ lỗi#

Hiển thị tài liệu#

Tuân thủ OAS#

OAS Key#

OAS Extensions#

Câu hỏi thường gặp#

Cấu hình nhiều ví dụ về body của yêu cầu

Trích xuất tham số yêu cầu dưới dạng ví dụ

Kịch bản sử dụng

Sử dụng ví dụ về body của yêu cầu trong khi gỡ lỗi

Hiển thị tài liệu

Tuân thủ OAS

OAS Key

OAS Extensions

Câu hỏi thường gặp