关于如何记录 Websocket API 的建议 [关闭]

Posted 2023-04-18

【中文标题】关于如何记录 Websocket API 的建议 [关闭]

【英文标题】：Recommendation on how to document Websocket API [closed]

【发布时间】：2016-05-06 10:49:16

【问题描述】：

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

假设在建立连接后，服务器等待login-事件，其负载类似于username: String, password: String。

然后服务器以事件login:accept 或login:deny 进行响应。

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

有没有一种标准化的方法来记录像这样的 API？您有什么建议和经验吗？

【参考方案1】：

AsyncApi node tool 用于创建机器可读的定义，它与 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"

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

话虽如此，使用socket.io的身份验证主要依赖于令牌，用户在连接启动时会在options.query中发送身份验证令牌，然后您在后端对令牌进行身份验证，然后您可以断开连接如果身份验证失败。不需要login:accept 或login:deny

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

【讨论】：

Something went wrong: Error: undefined is not a valid value for major version.

“命名空间”和“房间”呢？我们如何使用 asyncAPI 记录它们？