Phần mở rộng Đặc tả OpenAPI của Apidog

Apidog hỗ trợ các phần mở rộng đặc tả OpenAPI/Swagger tùy chỉnh nhằm nâng cao năng lực thiết kế và quản lý API. Các phần mở rộng này cho phép bạn chỉ định metadata bổ sung cho các endpoint API, chẳng hạn như cách tổ chức thư mục, trạng thái endpoint và thông tin người bảo trì.

Hướng dẫn tham chiếu này ghi lại các phần mở rộng x-apidog-* tùy chỉnh có thể được sử dụng trong đặc tả OpenAPI/Swagger của bạn để tích hợp liền mạch với các tính năng của Apidog.

Chỉ định thư mục mà endpoint thuộc về

Apidog sẽ ưu tiên sử dụng trường x-apidog-folder để tổ chức các endpoint. Nếu trường này không tồn tại, Apidog sẽ sử dụng giá trị đầu tiên trong trường tags.

Sử dụng dấu gạch chéo / để phân tách các thư mục nhiều cấp. Lưu ý rằng cả dấu gạch chéo ngược \ và dấu gạch chéo xuôi / đều là các ký tự đặc biệt cần được escape. Để biểu thị ký tự dấu gạch chéo xuôi /, vui lòng sử dụng \/, và để biểu thị ký tự \, vui lòng sử dụng \\.

Ví dụ:

"paths": {
  "/pets": {
     "post": {
         ...
         "operationId": "addPet",     
         "x-apidog-folder": "Pet Store/Pet Information"
     }
  }
}

Ví dụ về Swagger Annotation:

Tổ chức thư mục

Sử dụng tên thư mục có tính mô tả để tổ chức các endpoint của bạn một cách hợp lý. Điều này cải thiện khả năng điều hướng và giúp các thành viên trong nhóm nhanh chóng tìm thấy endpoint.

Trạng thái endpoint

Kiểm tra trạng thái của endpoint bằng trường x-apidog-status. Trường này cho phép bạn theo dõi vòng đời phát triển của từng endpoint API.

Các giá trị trạng thái khả dụng

Trạng thái	Mô tả
designing	(Đang thiết kế)
pending	(Đang chờ xử lý)
developing	(Đang phát triển)
integrating	(Đang tích hợp)
testing	(Đang kiểm thử)
tested	(Đã kiểm thử)
released	(Đã phát hành)
deprecated	(Không còn được khuyến nghị sử dụng)
exception	(Ngoại lệ)
obsolete	(Lỗi thời)
to be deprecated	(Sắp không còn được khuyến nghị sử dụng)

Ví dụ:

"paths": {
    "/pets": {
        "post": {
            ...
            "operationId": "addPet",     
            "x-apidog-status": "released"
        }
    }
}

Ví dụ về Swagger Annotation:

Theo dõi trạng thái

Trạng thái endpoint giúp các nhóm phối hợp nỗ lực phát triển và hiểu API nào đã sẵn sàng để sử dụng trong môi trường production.

Người bảo trì

Chỉ định người bảo trì cho một endpoint bằng trường x-apidog-maintainer. Giá trị của trường này là nickname hoặc username của người dùng Apidog trong nhóm.

Ví dụ:

"paths": {
    "/pets": {
        "post": {
            ...   
            "x-apidog-maintainer": "david"
        }
    }
}

Ví dụ về Swagger Annotation:

Quan trọng

Giá trị người bảo trì phải khớp với username hoặc nickname của một thành viên hiện có trong nhóm trên Apidog để việc gán được thực hiện chính xác.

Phần mở rộng Đặc tả OpenAPI của Apidog

Chỉ định thư mục mà endpoint thuộc về#

Trạng thái endpoint#

Các giá trị trạng thái khả dụng#

Người bảo trì#

Chỉ định thư mục mà endpoint thuộc về

Trạng thái endpoint

Các giá trị trạng thái khả dụng

Người bảo trì