使用AsyncAPI生成WebSocket文档时示例负载无法生成的求助

问题分析 #

你遇到的空白负载示例问题，核心原因是AsyncAPI 3.0.0的渲染工具（Studio/CLI）对嵌套schema中的example字段识别有限，仅在子schema定义示例无法触发工具生成完整的负载展示，需要在顶层schema或message payload级别明确提供完整的示例结构。

解决方案 #

下面提供两种可行的修改方式，任选其一即可：

方式一：在顶层Schema中添加完整示例 #

直接在BeginSchema中添加顶层example字段，定义完整的负载结构：

components:
  schemas:
    transactionNumber:
      type: integer
      description: a 4 digit transaction number. Generally unique to the client at that date.
      example: 50
    userId:
      type: integer
      description: unique identifier of the user.
      example: 100
    BeginSchema:
      type: object
      properties:
        transactionNumber:
          $ref: '#/components/schemas/transactionNumber'
        "action":
          type: string
          description: the action string
          enum:
            - "begin"
          example: "begin"
        userId:
          $ref: '#/components/schemas/userId'
      required:
        - transactionNumber
        - action
      # 添加顶层完整示例
      example:
        transactionNumber: 50
        action: "begin"
        userId: 100

方式二：在Message Payload中直接定义Examples #

在BeginAction消息的payload字段下添加examples数组，指定完整示例（此方式优先级更高，适合需要多示例的场景）：

components:
  messages:
    BeginAction:
      name: BeginAction
      title: Begin Action Message
      summary: >-
        Message informing the server that a new transaction begins
      contentType: application/json
      payload:
        schema: 
          $ref: '#/components/schemas/BeginSchema'
        # 添加消息级别的示例
        examples:
          - name: 标准开始动作示例
            value:
              transactionNumber: 50
              action: "begin"
              userId: 100

验证方法 #

修改完成后：

• 在AsyncAPI Studio中重新加载文档，即可看到负载示例正常显示
• 用Docker CLI重新生成HTML文档：

  docker run --rm -v $(pwd):/app asyncapi/cli generate fromTemplate -t @asyncapi/html-template /app/your-asyncapi-file.yaml -o /app/output
  

额外小修正 #

你的配置中servers.local.host使用了HTML转义字符<server-ip>，建议直接替换为<server-ip>，避免解析异常：

servers:
  local:
    host: '<server-ip>:5111'
    # 其他配置不变

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