SwaggerでWebSocketイベントまたはコールバックを文書化する方法
標準RESTを使用していくつかのリソースを取得できる設定があり、これはswaggerで簡単に文書化されます。同じリソースが変更されたときにWebSocketを使用してクライアントにプッシュされるため、クライアントは間隔ベースでプルを行う必要があります。
しかし、どうすればこれをswaggerで文書化できますか？可能ですか？そうでない場合、REST apiとwebsocketパーツの両方を文書化するために、他にどのツールを推奨しますか？
Swagger 3（またはOpenApi）は、Webhookを定義できるようにするコールバックの概念を追加した応答形式にアップグレードがあります。ドキュメントのこの部分を見てください： 応答フォーマット 。
Swagger 2で使用するのは、コールバックから期待するものとまったく同じものを実装するAPIメソッドを実装することです。コールバックを待機するメソッド。したがって、Swagger仕様を使用すると、どのコンシューマーも少なくとも私が期待しているメッセージのフォーマットを見ることができます。
今日、「非同期通信を使用してAPIを文書化する方法」について明確な答えを見つけることは困難です。これは、websocketだけでなく、 Server Send events などについても関係しています。
今日、Rest仕様については多くの有名な仕様があり、上位3つは次のとおりです。- Swagger - [〜＃〜] raml [〜＃〜] - APIブループリント
彼らはwebsocketを使用してAPIを文書化する方法について多くの問題/議論です...
しかし、Swaggerはコミュニティの助けを借りてAPI仕様を標準化しています。 OpenApi という名前です。
OpenAPI仕様のバージョン3では、 document webhook/callback への方法が導入されています。
もう1つの優れた仕様は asyncapi.com で、これはさらに深くなり、読み取り可能なopenApi仕様を尊重します。