如何在Swagger中定义包含复杂对象数组的示例请求体？

我明白你的需求啦——要给/myService这个POST接口设置一个包含多种不同复杂对象的数组作为默认请求体示例，方便用户测试。下面我给你两种常见版本的实现方案，你可以直接套用：

方案1：OpenAPI 3.x（推荐） #

OpenAPI 3.x对请求体和示例的支持更灵活，直接用requestBody来定义，示例写法也更直观：

openapi: 3.0.3
info:
  title: My Service API
  version: 1.0.0
paths:
  /myService:
    post:
      summary: test 123
      description: test 123
      requestBody:
        description: Array containing different complex objects
        required: true
        content:
          application/json:
            schema:
              type: array
              # 用oneOf指定数组元素可以是以下任意一种复杂对象
              items:
                oneOf:
                  - $ref: '#/components/schemas/ComplexTypeA'
                  - $ref: '#/components/schemas/ComplexTypeB'
            # 这里就是你要的默认示例，包含两种不同的复杂对象
            example:
              - id: 1
                name: "Type A Example"
                specificFieldA: "Only for Type A"
              - id: 2
                code: "TYPE_B"
                specificFieldB: 12345
                nestedObject:
                  key: "value"
components:
  schemas:
    ComplexTypeA:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        specificFieldA:
          type: string
      required: [id, name]
    ComplexTypeB:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        specificFieldB:
          type: integer
        nestedObject:
          type: object
          properties:
            key:
              type: string
      required: [id, code]

方案2：Swagger 2.0（旧版本） #

如果你的项目还在使用Swagger 2.0，就需要用parameters里的body参数来定义，示例写法如下：

swagger: '2.0'
info:
  title: My Service API
  version: 1.0.0
paths:
  /myService:
    post:
      summary: test 123
      description: test 123
      parameters:
        - name: bodyParamsObject
          description: Array containing different complex objects
          in: body
          required: true
          schema:
            type: array
            items:
              oneOf:
                - $ref: '#/definitions/ComplexTypeA'
                - $ref: '#/definitions/ComplexTypeB'
          # 默认示例数组
          example:
            - id: 1
              name: "Type A Example"
              specificFieldA: "Only for Type A"
            - id: 2
              code: "TYPE_B"
              specificFieldB: 12345
              nestedObject:
                key: "value"
definitions:
  ComplexTypeA:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      specificFieldA:
        type: string
    required: [id, name]
  ComplexTypeB:
    type: object
    properties:
      id:
        type: integer
      code:
        type: string
      specificFieldB:
        type: integer
      nestedObject:
        type: object
        properties:
          key:
            type: string
    required: [id, code]

关键要点说明 #

• oneOf的作用：它告诉Swagger，数组中的元素可以是指定的任意一种复杂对象，这样就支持混合不同类型的对象了
• 示例设置：直接在example字段里写你想要的测试数组，用户在Swagger UI里点击“Try it out”时，这个示例会自动填充到请求体里
• 自定义调整：你只需要把ComplexTypeA、ComplexTypeB换成你实际的复杂对象定义，把示例里的内容换成你的真实测试数据就行

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