Fern 定义高级

Fern Definition 中的 WebSockets

以 Markdown 格式查看

WebSockets 使用户能够与服务器创建连接，通过该连接可以发送双向通信。

在 Fern 中，您可以在 API 定义中指定 WebSockets。WebSockets 将包含在生成的 SDK 和 API 文档中。

WebSocket 定义

每个 WebSocket 都在自己的文件中定义，通过 channel 对象进行描述。将您的 WebSocket 定义文件放在 fern 文件夹中，与其他 API 定义文件一起。

fern
definition
api.yml
user.yml
chat.yml# WebSocket 定义
docs.yml

channel 对象

channel 由以下字段定义：

  • auth：WebSocket 的身份验证方案
  • path：WebSocket 的路径
  • headers （可选）：WebSocket 将发送的任何标头
  • path-parameters （可选）：WebSocket 路径中的任何路径参数
  • query-parameters （可选）：WebSocket 初始请求中使用的任何查询参数
  • messages （可选）：WebSocket 连接后可以发送和接收的消息模式
    • origin：发送消息的实体（例如 client 或 server）
    • body：消息的模式
  • examples：示例 WebSocket 连接 （可选）

WebSocket 示例

chat.yml
1channel:
2  path: /chat
3  auth: false
4  query-parameters:
5    model_id:
6      type: optional<string>
7      docs: The unique identifier of the model.
8    model_version:
9      type: optional<integer>
10      docs: The version number of the model.
11  messages:
12    publish:
13      origin: client
14      body: PublishEvent
15    subscribe:
16      origin: server
17      body: SubscribeEvent
18  examples: 
19    - query-parameters: 
20        model_id: "123"
21      messages: 
22        - type: publish
23          body:
24            text: "Hello, world."
25        - type: subscribe
26          body: 
27            id: "23823049"
28            message: "Hello there, how are you?"
29types:
30  PublishEvent:
31    docs: The input from the user to send through the WebSocket. 
32    properties: 
33      text: 
34        type: string
35        docs: The user text to send into the conversation. 
36  SubscribeEvent:
37    docs: The response from the server sent through the WebSocket.
38    properties: 
39      id: 
40        type: string
41        docs: The id of the message. 
42      message:
43        type: string
44        docs: The message sent through the socket.

WebSocket API 参考

WebSocket 参考

Fern 为 WebSockets 渲染独特的参考页面。握手部分概述了与服务器连接的协议，而发送和接收部分概述了客户端和服务器之间可以发送的消息模式。

用户可以直接在 API 参考中连接和使用 WebSockets（查看 Hume 的 WebSockets 这里）。

WebSocket 参考
Hume 的 WebSocket 参考页面