Swagger为对象属性添加多示例时出现结构错误的咨询

你的问题出在OpenAPI版本兼容性上：

• 你使用的Swagger Editor 3.6.31和Swagger UI 3.23.0对应OpenAPI 3.0规范，而属性字段下的examples（多示例）是OpenAPI 3.1才新增的特性。
• OpenAPI 3.0中，对象属性仅支持单示例的example字段，不允许使用多示例结构的examples，这就是编辑器报“不应包含附加属性examples”的原因。

两种可行的解决方案 #

方案1：改用单示例（符合OpenAPI 3.0规范） #

把examples替换为example，只保留单个示例值：

partitionProperty:
  type: string
  description: foobar
  example: 2016-03-04T03:00:00

方案2：将多示例移至接口的响应/请求体中（实现多示例展示） #

如果需要保留多示例，可以在具体接口的响应（或请求体）定义里添加examples，而不是在Schema属性中：

paths:
  /your-endpoint:
    get:
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainObject'
              examples:
                sampleExample1:
                  summary: 示例1
                  value:
                    partitionProperty: 2016-03-04T03:00:00
                    fooRequired: "index-1"
                sampleExample2:
                  summary: 示例2
                  value:
                    partitionProperty: 2024-01-01T00:00:00
                    fooRequired: "index-2"

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