Làm thế nào để ghi lại các sự kiện websocket hoặc gọi lại trong swagger

Question

Tôi có một thiết lập nơi có thể lấy một số tài nguyên bằng cách sử dụng REST tiêu chuẩn và điều này dễ dàng được ghi lại trong vênh vang. Cùng một tài nguyên được đẩy tới các máy khách bằng cách sử dụng các websockets khi nó đã thay đổi, vì vậy các máy khách không phải thực hiện một pull trên cơ sở khoảng thời gian.

Nhưng làm cách nào tôi có thể ghi lại điều này trong vênh vang? Thậm chí có thể không? Nếu không, bạn đề nghị công cụ nào khác để ghi lại cả phần REST và phần Websocket?

Answer 1

Thông số Swagger xác định một nhóm hoạt động giới hạn, mà bạn có thể xác định cho một số path object cụ thể trong lược đồ của mình. Điều đó đang được nói, bạn được tự do bước ra ngoài thông số kỹ thuật nếu bạn chỉ quan tâm đến việc ghi lại API của bạn để sử dụng cho con người. Hãy xem ví dụ WIX docs. Nó sử dụng định nghĩa HOOK tùy chỉnh để ghi lại API webhook của nó và nó không giả vờ là một thông số Swagger hợp lệ, có thể chỉ là những gì bạn cần trong trường hợp của bạn.

Answer 2

Rất khó để tìm câu trả lời rõ ràng về "Cách ghi tài liệu apis bằng cách sử dụng giao tiếp không đồng bộ". Nó không chỉ về WebSocket mà còn Server Send events và những người khác ....

Hôm nay, đối với đặc điểm kỹ thuật phần còn lại, có rất nhiều thông số kỹ thuật nổi tiếng và top 3 là: - Swagger - RAML - API Blue Print

Họ có rất nhiều vấn đề/thảo luận về cách ghi lại apis bằng cách sử dụng websocket, ...

Nhưng Swagger đang chuẩn hóa đặc tả api với sự trợ giúp của cộng đồng. Nó được đặt tên là OpenApi.

Phiên bản 3 của thông số kỹ thuật OpenAPI giới thiệu một cách đến document webhook/callback.

Một đặc điểm kỹ thuật khác là asyncapi.com, điều này sẽ đi sâu hơn và tôn trọng thông số kỹ thuật openApi có thể đọc được.

Answer 3

Swagger 3 (hoặc OpenApi) có bản nâng cấp ở định dạng phản hồi nơi họ thêm khái niệm gọi lại, cho phép bạn xác định webhook. Hãy xem phần tài liệu này: response format.

Trong Swagger 2 những gì tôi sử dụng để làm là triển khai phương pháp API thực hiện chính xác như tôi mong đợi từ một cuộc gọi lại và tôi chỉ tham chiếu nó theo phương thức ban đầu chờ đợi cuộc gọi lại. Vì vậy, bất kỳ người tiêu dùng nào cũng có thể thấy định dạng của thông điệp mà tôi mong đợi từ họ, bằng cách sử dụng đặc tả Swagger.