关于如何记录 Websocket API 的建议

Question

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

假设建立连接后，服务器等待具有有效负载的 login -事件，例如 {username: String, password: String} .

然后，服务器使用事件login:accept或login:deny进行应答。

仅当登录成功时，服务器才会使用事件tweets（将推文数组作为有效负载）响应事件tweets:get。

有没有一种标准化的方式来记录这样的 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' } });