Cách thêm nhiều ví dụ về nội dung yêu cầu trong Apidog

Apidog hỗ trợ thêm nhiều ví dụ về thân yêu cầu cho mỗi endpoint, giúp tài liệu API của bạn hữu ích hơn và tương thích với các tiêu chuẩn OpenAPI. Tính năng này cho phép bạn trình bày các cách khác nhau để cấu trúc yêu cầu cho cùng một endpoint, điều này giúp các nhà phát triển hiểu cách sử dụng API của bạn trong nhiều tình huống khác nhau.

Các ví dụ về thân yêu cầu rất hữu ích bởi vì chúng:

Cho các nhà phát triển biết chính xác cách định dạng yêu cầu của họ
Chứng minh các trường hợp sử dụng khác nhau cho cùng một endpoint
Giúp việc kiểm tra trở nên dễ dàng hơn bằng cách cung cấp các cấu trúc yêu cầu đã sẵn sàng để sử dụng
Đảm bảo tài liệu của bạn tuân thủ các tiêu chuẩn OpenAPI

Bạn có thể thêm nhiều ví dụ mà bạn cần để bao quát tất cả các kịch bản có thể xảy ra.

Các bước: Thêm ví dụ về thân yêu cầu đầu tiên của bạn

Thêm các ví dụ về thân yêu cầu trong Apidog rất đơn giản. Đây là cách để bắt đầu:

1. Mở dự án API của bạn trong Apidog (phiên bản 2.7.0 trở lên)

2. Chuyển đến endpoint nơi bạn muốn thêm ví dụ

3. Nhấp vào tab "Chỉnh sửa" để truy cập vào trình chỉnh sửa tài liệu và Cuộn xuống phần "Thân yêu cầu"

4. Nhấp vào "Thêm Ví dụ" để tạo một ví dụ mới

5. Điền thông tin chi tiết về ví dụ:

Tên Ví dụ: Đặt tên rõ ràng cho ví dụ của bạn (ví dụ: "Yêu cầu tiêu chuẩn")
Giá trị Ví dụ: Nhập dữ liệu JSON, XML hoặc định dạng khác
Mô tả: Giải thích khi nào nên sử dụng ví dụ này (hỗ trợ Markdown)
Khóa OAS: Cung cấp một định danh cho xuất OpenAPI (tùy chọn nhưng được khuyến nghị)
Mở rộng OAS: Thêm bất kỳ trường tùy chỉnh nào cần thiết cho xuất (tùy chọn)

6. Nhấp vào "Lưu" để tạo ví dụ

Tên ví dụ giúp người dùng xác định mục đích của mỗi ví dụ. Nếu bạn để trống, Apidog sẽ tự động đặt tên là "Ví dụ 1," "Ví dụ 2," v.v.

Giá trị ví dụ nên hiển thị một cấu trúc yêu cầu hợp lệ. Đối với các loại nội dung JSON, Apidog cung cấp một trình chỉnh sửa có cấu trúc để giúp đảm bảo định dạng hợp lệ.

Trường mô tả là nơi bạn có thể giải thích khi nào và tại sao ai đó sẽ sử dụng cấu trúc yêu cầu cụ thể này. Sử dụng Markdown ở đây có thể làm cho các giải thích của bạn trở nên rõ ràng hơn.

Khóa OAS là rất quan trọng nếu bạn dự định xuất tài liệu của mình sang định dạng OpenAPI. Khóa này trở thành định danh cho ví dụ trong tài liệu xuất khẩu.

Tạo Nhiều Ví dụ cho Các Kịch Bản Khác Nhau

Sau khi thêm ví dụ đầu tiên, bạn sẽ muốn tạo thêm các ví dụ cho các trường hợp sử dụng khác nhau:

Nhấp vào nút "+ Thêm" lần nữa để tạo một ví dụ khác
Đặt tên cho nó một cách đặc biệt để xác định rõ kịch bản (ví dụ: "Yêu cầu tối thiểu")
Nhập giá trị ví dụ cho kịch bản cụ thể này
Thêm một mô tả chi tiết giải thích khi nào nên sử dụng ví dụ này
Cấu hình Khóa OAS và Mở rộng khi cần thiết
Nhấp vào "Lưu" để thêm ví dụ
lặp lại quy trình này cho tất cả các kịch bản liên quan

thêm một ví dụ về thân yêu cầu khác trong tài liệu endpoint

Khi tạo nhiều ví dụ, hãy xem xét bao quát những kịch bản phổ biến này:

Yêu cầu Tiêu chuẩn: Cách sử dụng điển hình cho endpoint
Yêu cầu Tối thiểu: Cấu trúc yêu cầu hợp lệ đơn giản nhất
Yêu cầu Hoàn chỉnh: Một yêu cầu sử dụng tất cả các trường có thể có
Trường hợp Đặc biệt: Các ví dụ cho các kịch bản kinh doanh độc đáo

Mỗi ví dụ nên cho thấy một cách khác nhau để sử dụng endpoint. Điều này giúp các nhà phát triển hiểu đầy đủ các khả năng khi làm việc với API của bạn.

Apidog hiển thị các ví dụ theo một thứ tự cụ thể:

Các ví dụ có tên sẽ đứng trước các ví dụ không có tên
Các ví dụ có Khóa OAS được hiển thị trước những ví dụ không có
Các ví dụ không có tên hoặc Khóa OAS được sắp xếp theo số serial của chúng

tài liệu các ví dụ về thân yêu cầu bằng cách sử dụng Apidog

Để làm cho các ví dụ quan trọng nhất của bạn xuất hiện trước, hãy đặt tên rõ ràng và cung cấp Khóa OAS cho chúng.

Sử dụng Các Ví dụ về Thân Yêu Cầu để Kiểm Tra

Một trong những tính năng tốt nhất của các ví dụ về thân yêu cầu là cách chúng đơn giản hóa việc kiểm tra:

Chuyển đến trang "Chạy" của endpoint của bạn
Tìm phần "Tự động tạo" trong cấu hình yêu cầu
Nhấp vào menu thả xuống để xem tất cả các ví dụ có sẵn
Chọn ví dụ mà bạn muốn kiểm tra
Thân yêu cầu sẽ tự động được điền với ví dụ đã chọn
Nhấp vào "Gửi" để kiểm tra endpoint với ví dụ này

Sử dụng các ví dụ về thân yêu cầu để kiểm tra

Điều này giúp dễ dàng kiểm tra các kịch bản khác nhau mà không cần phải gõ hoặc dán các cấu trúc yêu cầu khác nhau một cách thủ công. Bạn có thể nhanh chóng chuyển đổi giữa các ví dụ để xem cách API của bạn xử lý các đầu vào khác nhau.

Apidog cũng cho phép bạn tạo ví dụ từ các phiên kiểm tra của bạn:

Cấu hình một thân yêu cầu trên trang "Chạy"
Nhấp vào nút "Trích xuất"
Chọn "Trích xuất để làm Ví dụ Yêu cầu"
Chọn để tạo một ví dụ mới hoặc cập nhật một ví dụ hiện có
Thân yêu cầu hiện tại của bạn sẽ được lưu lại như một ví dụ

Điều này rất hữu ích khi bạn đã tìm thấy một cấu trúc yêu cầu hoạt động trong quá trình kiểm tra và muốn lưu lại để tham khảo hoặc tài liệu trong tương lai.

Đảm bảo Tính Tương Thích với OpenAPI cho Các Ví Dụ của Bạn

Các ví dụ về thân yêu cầu của Apidog được thiết kế để hoạt động liền mạch với các tiêu chuẩn OpenAPI. Khi bạn xuất tài liệu API của bạn, tất cả các ví dụ của bạn đều được định dạng đúng theo các tiêu chuẩn OAS 3.0/3.1.

Dưới đây là cách mà các ví dụ được xử lý trong quá trình xuất:

Mỗi ví dụ được bao gồm trong tài liệu xuất khẩu
Tên ví dụ đến từ Khóa OAS nếu có (hoặc số serial nếu không có)
Mô tả ví dụ được bảo toàn trong định dạng xuất khẩu
Bất kỳ Mở rộng OAS tùy chỉnh nào đều được bao gồm trong xuất khẩu

Tài liệu OpenAPI xuất khẩu sẽ bao gồm các ví dụ của bạn trong một cấu trúc như sau:

"examples": {
  "standard_request": {
    "value": {
      "name": "John Doe",
      "id": "12345",
      "email": "john.doe@example.com"
    },
    "summary": "Yêu cầu tiêu chuẩn",
    "description": "Đây là một yêu cầu tiêu chuẩn với tất cả các trường cần thiết."
  },
  "minimal_request": {
    "value": {
      "id": "12345"
    },
    "summary": "Yêu cầu tối thiểu",
    "description": "Đây là một yêu cầu tối thiểu chỉ với trường ID cần thiết."
  }
}

Để đảm bảo tính tương thích tốt nhất với OpenAPI:

Sử dụng các Khóa OAS có ý nghĩa cho tất cả các ví dụ
Cung cấp các mô tả rõ ràng giải thích mục đích của từng ví dụ
Rà soát các thông số đã xuất khẩu để xác minh mọi thứ trông đúng

Điều này đảm bảo rằng các ví dụ của bạn vẫn có giá trị không chỉ trong Apidog mà còn khi được chia sẻ thông qua các tiêu chuẩn OpenAPI.

Thực Hành Tốt Nhất cho Các Ví Dụ về Thân Yêu Cầu

Để thu được giá trị lớn nhất từ các ví dụ về thân yêu cầu, hãy tuân theo các thực hành tốt nhất này:

Tạo Bộ Ví Dụ Đầy Đủ

Bao gồm các ví dụ bao quát:

Sử dụng cơ bản chỉ với các trường cần thiết
Sử dụng điển hình với các trường tùy chọn thường được sử dụng
Sử dụng hoàn chỉnh hiển thị tất cả các trường có thể có
Trường hợp Biên chứng minh các tình huống đặc biệt

Sử Dụng Tên Rõ Ràng

Đặt tên cho mỗi ví dụ với một mô tả rõ ràng chỉ ra mục đích của nó
Sử dụng các mẫu đặt tên nhất quán giữa các endpoint khác nhau
Tránh các tên chung chung như "Ví dụ 1" mà không giải thích được nội dung

Viết Mô Tả Hữu Ích

Giải thích khi nào và tại sao ai đó sẽ sử dụng mỗi ví dụ
Đề cập đến bất kỳ cân nhắc đặc biệt nào cho cấu trúc yêu cầu này
Sử dụng định dạng Markdown để làm cho các mô tả dễ đọc hơn
bao gồm các phản hồi mong đợi khi có liên quan

Sắp Xếp Các Ví Dụ một cách Hợp Lý

Đưa ra những kịch bản phổ biến nhất trước
Nhóm các ví dụ liên quan lại với nhau
Xóa các ví dụ lỗi thời để tránh nhầm lẫn
Cập nhật các ví dụ khi API của bạn thay đổi

Sử Dụng Các Khóa OAS Hiệu Quả

Chọn các khóa có ý nghĩa mô tả mục đích của ví dụ
Sử dụng các tên khóa nhất quán trong toàn bộ API của bạn
Tránh các ký tự đặc biệt có thể gây ra vấn đề trong các xuất khẩu

Bằng cách tuân theo những thực hành này, bạn sẽ tạo ra các ví dụ về thân yêu cầu thực sự giúp các nhà phát triển hiểu và sử dụng API của bạn một cách hiệu quả.

Kết Luận

Thêm nhiều ví dụ về thân yêu cầu trong Apidog là một cách đơn giản nhưng mạnh mẽ để cải thiện tài liệu API của bạn. Bằng cách trình bày các cách khác nhau để cấu trúc yêu cầu cho cùng một endpoint, bạn giúp các nhà phát triển hiểu cách sử dụng API của bạn trong nhiều tình huống khác nhau.

Quy trình từng bước rất đơn giản:

Chuyển đến endpoint của bạn và nhấp vào "Chỉnh sửa"
Cuộn xuống phần Thân Yêu cầu và nhấp vào "+ Thêm"
Cấu hình ví dụ của bạn với tên, giá trị, mô tả và Khóa OAS
lặp lại cho các kịch bản bổ sung
Sử dụng các ví dụ của bạn cho quá trình kiểm tra và tài liệu

Với các ví dụ rõ ràng và đầy đủ, API của bạn trở nên dễ hiểu, dễ kiểm tra và triển khai hơn. Điều này dẫn đến việc áp dụng nhanh hơn, ít câu hỏi hỗ trợ hơn và trải nghiệm của nhà phát triển tốt hơn tổng thể.

Bắt đầu thêm nhiều ví dụ về thân yêu cầu vào tài liệu Apidog của bạn hôm nay để thấy rõ lợi ích cho chính bạn và người dùng API của bạn.

button