如何规范化描述Websocket API？当前相关规范及文档现状如何？

背景 #

REST及其他同步API可通过OpenAPI规范清晰定义，还能借助Swagger等平台自动生成文档与代码，但该规范并不适用于描述WebSocket协议。早在6年前，就有人在Stack Exchange上提出了「如何用Swagger描述WebSocket API」的相关问题。

当前标准化方案 #

专门为异步API设计的AsyncAPI规范，初期确实更偏向MQTT这类传统发布/订阅协议，但目前已经对WebSocket提供了完善的支持：它可以定义WebSocket的连接参数、消息结构（含请求与响应字段）、订阅/推送规则等，是当前描述WebSocket API的主流标准化方案。

此外，不少工具生态也围绕AsyncAPI扩展了WebSocket相关能力，比如可以生成交互式文档、客户端代码，甚至进行API模拟测试，解决了WebSocket API长期缺乏统一规范定义的问题。

行业落地案例 #

不少交易平台已经公开了成熟的WebSocket API文档，典型案例包括：

• Kraken：提供覆盖实时行情、订单状态推送等场景的WebSocket接口文档，明确了消息格式、字段定义及交互流程
• Gemini：其WebSocket API文档详细说明了连接建立、频道订阅、消息解析等全流程细节，支持实时交易数据的获取

内容的提问来源于stack exchange，提问作者ShooShoo