关于如何记录Websocket API的建议

Question

我使用socket.io编写了一个Websocket-API.

假设在建立连接之后,服务器等待login有效负载的-event {username: String, password: String}.

然后服务器回答事件login:accept或login:deny.

只有登录成功后,服务器才会响应具有事件tweets:get的事件tweets(具有一系列推文作为有效负载).

是否有标准化的方式来记录这样的API？你有什么建议和经验吗？

Answer 1

有AsyncApi节点工具来创建机器可读的定义,它非常类似于swagger,但对于异步API,还有生成HTML的工具,如AsyncApi docgen和widdershins.

您可以使用yaml或构建文档json,例如:

asyncapi: "1.0.0"

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

其中topics= events,publish= emit和subscribe= on在socket.io术语中

在说完后,使用socket.io的身份验证主要依赖于令牌,用户将options.query在连接启动时发送身份验证令牌,并在后端验证令牌,然后如果身份验证失败,您可以断开连接.不需要login:accept或login:deny

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