Websocket APIを文書化するための推奨方法

Question

socket.ioを使用してWebsocket-APIを作成しました。

接続が確立された後、サーバはのようなペイロードでloginイベントを待ちます。

サーバーは、イベントlogin:acceptまたはlogin:denyで応答します。

ログインが成功した場合のみ、サーバーはイベントに応答し、イベントtweets（ペイロードとしてのつぶやきの配列を持つ）を返します。

このようなAPIを文書化する標準的な方法はありますか？お勧めや経験はありますか？

Answer 1

AsyncApi node toolは機械可読の定義を作成するためのものです。これはswaggerと非常によく似ていますが、非同期APIの場合はAsyncApi docgenやwiddershinsなどのHTMLを生成するツールがあります。

あなたは一例として、yamlまたはjsonのいずれかを使用してドキュメントを構築することができます：

asyncapi: "1.0.0" 

topics: 
    "tweets:get": 
     publish: 
      $ref: "#/components/messages/getTweets" 
    tweets: 
     subscribe: 
      $ref: "#/components/messages/tweetsList" 

= eventstopics、= emitpublish、およびsocket.io的に= onsubscribe

socket.ioを使った認証はトークンに依存していると言いますと、ユーザはに認証トークンを送ります接続開始時にを呼び出し、バックエンドでトークンを認証すると、認証が失敗した場合に接続を切断できます。 @kordy login:acceptまたはlogin:deny

const socket = io('http://localhost?token=abc'); 
// or 
const socket = io({ query: { token: 'cde' } });