OpenAPI 3.x中POST /orders请求体与200响应同步问题咨询

要实现请求体类型和响应的自动同步，核心是正确配置discriminator（鉴别器），同时给每个类型添加专属的描述和示例。以下是具体的修正方案：

1. 修正Schema结构，添加鉴别属性 #

首先给两个请求体Schema添加共同的鉴别属性（比如createOrderItemType），并为每个Schema指定固定值，让OpenAPI能明确区分不同类型：

components:
  schemas:
    slimcollectVerify:
      description: A representation of slimcollectVerify
      type: object
      required:
        - createOrderItemType
        - huntingSkillSCVerifiy
      properties:
        createOrderItemType:
          type: string
          enum:
            - slimcollectVerify
          default: slimcollectVerify
          description: 标识请求/响应类型为slimcollectVerify
        huntingSkillSCVerifiy:
          type: string
          description: The measured skill for Verify
          default: lazy
          example: adventurous
          enum:
            - clueless
            - lazy
    slimcollectPayUnsigned:
      description: A representation of slimcollectPayUnsigned
      type: object
      required:
        - createOrderItemType
        - huntingSkillSCPayUnsigned
      properties:
        createOrderItemType:
          type: string
          enum:
            - slimcollectPayUnsigned
          default: slimcollectPayUnsigned
          description: 标识请求/响应类型为slimcollectPayUnsigned
        huntingSkillSCPayUnsigned:
          type: string
          description: The measured skill for PayUNsigned
          default: lazy
          example: adventurous
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive

2. 配置请求体的Discriminator #

在请求体的Schema中启用discriminator，指定鉴别属性名，并映射到对应的Schema，同时为每个类型添加专属示例：

components:
  requestBodies:
    CreateOrder:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/slimcollectVerify'
              - $ref: '#/components/schemas/slimcollectPayUnsigned'
            discriminator:
              propertyName: createOrderItemType
              mapping:
                slimcollectVerify: '#/components/schemas/slimcollectVerify'
                slimcollectPayUnsigned: '#/components/schemas/slimcollectPayUnsigned'
          examples:
            slimcollectVerifyExample:
              summary: slimcollectVerify类型请求示例
              value:
                createOrderItemType: slimcollectVerify
                huntingSkillSCVerifiy: adventurous
            slimcollectPayUnsignedExample:
              summary: slimcollectPayUnsigned类型请求示例
              value:
                createOrderItemType: slimcollectPayUnsigned
                huntingSkillSCPayUnsigned: aggressive
      description: Request Body of the create order
      required: true

3. 配置响应与请求体同步 #

在200响应中同样配置discriminator，并为每个响应类型添加专属描述和示例，实现请求体与响应的联动：

paths:
  /orders:
    post:
      tags:
        - pet
      summary: Create an order
      description: Command to create an order.
      operationId: createOrder
      responses:
        '200':
          description: 成功操作（根据请求类型返回对应响应）
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/slimcollectVerify'
                  - $ref: '#/components/schemas/slimcollectPayUnsigned'
                discriminator:
                  propertyName: createOrderItemType
                  mapping:
                    slimcollectVerify: '#/components/schemas/slimcollectVerify'
                    slimcollectPayUnsigned: '#/components/schemas/slimcollectPayUnsigned'
              examples:
                slimcollectVerifyResponse:
                  summary: slimcollectVerify类型响应示例
                  description: 当请求为slimcollectVerify时返回此响应
                  value:
                    createOrderItemType: slimcollectVerify
                    huntingSkillSCVerifiy: lazy
                slimcollectPayUnsignedResponse:
                  summary: slimcollectPayUnsigned类型响应示例
                  description: 当请求为slimcollectPayUnsigned时返回此响应
                  value:
                    createOrderItemType: slimcollectPayUnsigned
                    huntingSkillSCPayUnsigned: adventurous
        '405':
          description: Invalid input
      requestBody:
        $ref: '#/components/requestBodies/CreateOrder'

关键注意事项 #

• 鉴别属性是核心：createOrderItemType必须在每个Schema中声明为必填，且有固定枚举值，Redocly才能基于这个属性自动关联请求体和响应。
• 示例绑定：给请求体和响应分别添加对应类型的示例后，Redocly预览界面会在选择请求体类型时，自动切换到对应的响应示例和描述。
• 生效步骤：配置完成后重新执行你的Redocly命令即可生效：

  redocly bundle openapi.yaml --output bundled.yaml
  redocly preview-docs bundled.yaml
  

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