如何在OpenAPI YAML中为已定义组件的数组字段设置示例值

你现在Datasources渲染为对象而非数组，是因为示例配置结构不符合JSON数组语法，同时大概率误将XML包裹标签的逻辑用到了JSON示例的写法里。你之前期望写法里Datasources: [ Datasource: { ... } ]也不符合标准JSON语法，数组内不需要额外加Datasource键。

1. 保留原有组件定义不变 #

你现有的Template组件里Datasources字段的类型定义是正确的，不需要修改，xml: wrapped: true配置仅作用于XML序列化场景，不会影响JSON结构的渲染。

2. 按数组格式写请求示例 #

方案A：在接口请求体中配置示例 #

paths:
  /你的接口路径:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
            # 正确示例写法
            example:
              Callback: "https://你的回调地址/{guid}"
              OutputFormat: "pdf"
              Data: "base64编码的模板字符串"
              Datasources:
              - Name: "数据源1"
                Type: "json"
                ConnectionString: "数据源连接地址"
              - Name: "数据源2"
                Type: "sql"
                ConnectionString: "数据库连接串"
              # 其他Template字段按需补充

方案B：在Template组件中配置全局示例 #

如果希望所有引用Template的地方都复用同一个示例，可以直接在组件定义下加example字段：

components:
  schemas:
    Template:
      type: object
      properties:
        # 原有所有属性定义保持不变
      # 新增全局示例
      example:
        OutputFormat: "docx"
        Datasources:
        - Name: "销售数据"
          Type: "xlsx"
          ConnectionString: "..."
        - Name: "人员信息"
          Type: "json"
          ConnectionString: "..."

如果你调整写法后Swagger Editor报错，基本是以下两种情况：

• 示例中Datasources字段类型不匹配：给数组类型的字段赋值了对象，比如写成Datasources: { Datasource: {...} }
• Datasource对象内部字段不符合你定义的Datasource组件要求，缺少必填字段或者字段类型错误

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