api - restful - Cómo documentar eventos websocket o devolución de llamada en swagger
swagger guia (3)
Tengo una configuración donde es posible obtener algún recurso utilizando REST estándar y esto es fácil de documentar. El mismo recurso se envía a los clientes que usan websockets cuando ha cambiado, por lo que los clientes no tienen que realizar una extracción a intervalos.
Pero, ¿cómo puedo documentar esto en swagger? ¿Es incluso posible? Si no, ¿qué otra herramienta recomienda para documentar tanto la API REST como la parte websocket?
Hoy en día es difícil encontrar una respuesta clara sobre "Cómo documentar apis utilizando una comunicación asíncrona". No se trata solo de websocket sino también de eventos de Server Send y otros ...
Hoy, para la especificación Rest, hay muchas especificaciones famosas y las 3 principales son: - Swagger - RAML - API Blue Print
Son muchos temas / discusiones sobre una forma de documentar apis usando websocket, ...
Pero Swagger está estandarizando la especificación de api con la ayuda de la comunidad. Se llama OpenApi .
La versión 3 de las especificaciones de OpenAPI presenta una forma de documentar el webhook / callback .
Otra buena especificación es asyncapi.com que profundiza y respeta las especificaciones legibles de openApi.
Swagger 3 (o OpenApi) tiene una actualización en los formatos de respuesta donde agregaron el concepto de devoluciones de llamada, que le permiten definir un webhook. Eche un vistazo a esta parte de la documentación: formato de respuesta .
En Swagger 2, lo que suelo hacer es implementar un método de API que implemente exactamente lo mismo que espero de una devolución de llamada y simplemente lo menciono en el método original que espera la devolución de llamada. Por lo tanto, cualquier consumidor puede ver al menos el formato del mensaje que estoy esperando de ellos, utilizando la especificación Swagger.
La especificación Swagger define un conjunto limitado de operaciones, que puede definir para un objeto de ruta en particular en su esquema. Dicho esto, usted es libre de salir de la especificación si solo le importa documentar su API para uso humano. Echa un vistazo a los documentos de WIX, por ejemplo. Utiliza una definición HOOK personalizada para documentar su API de webhook y no pretende ser una especificación de Swagger válida, que puede ser justo lo que necesita en su caso.