OpenAPI 3.0+Redoc：如何DRY化定义带条件嵌套对象的API组件

嘿，这个问题我之前在维护OpenAPI文档的时候也碰到过——要处理同一个对象在不同端点有不同嵌套层级的情况，还得严格遵循DRY原则，确实得费点心思。下面给你几个实用的解决方案，你可以根据自己的API结构挑最合适的：

这是最贴合DRY原则的方案：先定义每个对象的基础版本（不含可选嵌套），再通过allOf叠加差异属性生成扩展版本。这样所有重复的字段只写一次，不同端点按需引用对应的组件即可。

举个具体的YAML示例：

components:
  schemas:
    # 先定义最底层的ObjectC
    ObjectC:
      type: object
      properties:
        c_prop:
          type: string
    
    # 基础版ObjectB：不含ObjectC，所有端点共用这部分字段
    ObjectBBase:
      type: object
      properties:
        b_prop:
          type: string
    
    # 扩展版ObjectB：在基础版上新增ObjectC嵌套
    ObjectBWithC:
      allOf:
        - $ref: '#/components/schemas/ObjectBBase'
        - type: object
          properties:
            objectC:
              $ref: '#/components/schemas/ObjectC'
    
    # 端点1用的ObjectA：引用带C的ObjectB
    ObjectA_Endpoint1:
      type: object
      properties:
        a_prop:
          type: string
        objectB:
          $ref: '#/components/schemas/ObjectBWithC'
    
    # 端点2用的ObjectA：引用基础版ObjectB
    ObjectA_Endpoint2:
      type: object
      properties:
        a_prop:
          type: string
        objectB:
          $ref: '#/components/schemas/ObjectBBase'

这个方案的优势很明显：完全避免重复代码，Redoc也能完美渲染allOf组合的结构，会自动把基础属性和扩展属性合并展示给用户。

如果你的API中，ObjectB的不同版本有明确的标识字段（比如b_type）来区分，那用oneOf加鉴别器会更清晰，还能让API工具自动校验请求/响应的结构是否匹配对应的变体。

示例代码：

components:
  schemas:
    ObjectC:
      type: object
      properties:
        c_prop:
          type: string
    
    # 顶层ObjectB：声明所有可能的变体
    ObjectB:
      oneOf:
        - $ref: '#/components/schemas/ObjectB_Basic'
        - $ref: '#/components/schemas/ObjectB_WithC'
      discriminator:
        propertyName: b_type
        mapping:
          basic: '#/components/schemas/ObjectB_Basic'
          with_c: '#/components/schemas/ObjectB_WithC'
    
    # 基础版ObjectB：带鉴别器标识
    ObjectB_Basic:
      type: object
      required: [b_type]
      properties:
        b_type:
          type: string
          enum: [basic]
        b_prop:
          type: string
    
    # 带C的ObjectB：带鉴别器标识
    ObjectB_WithC:
      type: object
      required: [b_type]
      properties:
        b_type:
          type: string
          enum: [with_c]
        b_prop:
          type: string
        objectC:
          $ref: '#/components/schemas/ObjectC'

这个方案适合需要明确区分对象变体的场景，Redoc会展示所有可能的结构，并通过鉴别器字段引导用户理解不同版本的差异。

如果你的需求只是“ObjectC可选存在”，而不是严格的“完全没有这个字段”，可以把ObjectC设为可空，然后在不同端点的请求/响应里控制它是否必填。如果需要严格禁止字段出现，还可以用not: {}来约束。

示例：

components:
  schemas:
    ObjectC:
      type: object
      properties:
        c_prop:
          type: string
    
    ObjectB:
      type: object
      properties:
        b_prop:
          type: string
        objectC:
          $ref: '#/components/schemas/ObjectC'
          nullable: true # OpenAPI 3.0用nullable，3.1可直接写type: object|null
    
    ObjectA:
      type: object
      properties:
        a_prop:
          type: string
        objectB:
          $ref: '#/components/schemas/ObjectB'

paths:
  # 端点1：要求ObjectB必须包含ObjectC
  /endpoint1:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ObjectA'
                  - type: object
                    properties:
                      objectB:
                        required: [objectC]
  
  # 端点2：禁止ObjectB包含ObjectC
  /endpoint2:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ObjectA'
                  - type: object
                    properties:
                      objectB:
                        properties:
                          objectC:
                            not: {} # 约束该字段不能存在

这个方案适合简单的可选嵌套场景，但要注意不是所有API工具都完美支持not: {}约束，不过Redoc是能识别并展示这个规则的。

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