Как документировать события websocket или обратный вызов в swagger
У меня есть настройка, где можно получить некоторый ресурс, используя стандартный REST, и это легко задокументировано в swagger. Тот же ресурс переносится на клиентов, использующих веб-порты, когда он изменился, поэтому клиентам не нужно делать паузу с интервалом.
Но как я могу документировать это в чванстве? Возможно ли это? Если нет, какой другой инструмент вы рекомендуете для документирования как REST api, так и части websocket?
Ответы
Ответ 1
Спецификация Swagger определяет ограниченный набор операций, которые вы можете определить для определенного объекта пути в вашей схеме. При этом вы можете выйти за пределы спецификации, если вам небезразлично документировать ваш API для использования человеком. Посмотрите WIX docs, например. Он использует пользовательское определение HOOK для документирования своего API веб-хостинга и не претендует на то, чтобы быть действительной спецификацией Swagger, которая может быть именно тем, что вам нужно в вашем случае.
Ответ 2
Swagger 3 (или OpenApi) имеет обновление в форматах ответов, где они добавили концепцию обратных вызовов, которые позволяют вам определять веб-хост. Взгляните на эту часть документации: формат ответа.
В Swagger 2 я использую API-метод, который реализует точно то же самое, что я ожидаю от обратного вызова, и я просто ссылаюсь на него в исходном методе, который ждет обратного вызова. Поэтому любой потребитель может хотя бы увидеть формат сообщения, который я ожидаю от них, используя спецификацию Swagger.
Ответ 3
Сегодня сложно найти четкий ответ на тему "Как документировать apis, используя асинхронную связь". Речь идет не только о websocket, но также событиях отправки сервера и других.
Сегодня для спецификации Rest есть много известных спецификаций, а топ-3:
- Swagger
- RAML
- API Blue Print
Это много вопросов/дискуссий о способе документации apis с помощью websocket,...
Но Swagger стандартизирует спецификацию api с помощью сообщества. Он назвал OpenApi.
В версии 3 спецификаций OpenAPI представлен способ document webhook/callback.
Еще одна хорошая спецификация asyncapi.com, которая идет глубже и уважает доступные параметры openApi.
