跳到导航
Fern 定义高级

Fern 定义中的 WebSocket

以 Markdown 格式查看

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

在 Fern 中，你可以在 API 定义中指定 WebSocket。WebSocket 将包含在生成的 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
channel:
  path: /chat
  auth: false
  query-parameters:
    model_id:
      type: optional<string>
      docs: The unique identifier of the model.
    model_version:
      type: optional<integer>
      docs: The version number of the model.
  messages:
    publish:
      origin: client
      body: PublishEvent
    subscribe:
      origin: server
      body: SubscribeEvent
  examples: 
    - query-parameters: 
        model_id: "123"
      messages: 
        - type: publish
          body:
            text: "Hello, world."
        - type: subscribe
          body: 
            id: "23823049"
            message: "Hello there, how are you?"
types:
  PublishEvent:
    docs: The input from the user to send through the WebSocket. 
    properties: 
      text: 
        type: string
        docs: The user text to send into the conversation. 
  SubscribeEvent:
    docs: The response from the server sent through the WebSocket.
    properties: 
      id: 
        type: string
        docs: The id of the message. 
      message:
        type: string
        docs: The message sent through the socket.

WebSocket API 参考

WebSocket 参考

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

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

WebSocket 参考
Hume 的 WebSocket 参考页面