如何在Swagger中复用请求体公共字段？解决$ref覆盖问题

要解决$ref覆盖同层级字段的问题，你需要使用Swagger的allOf关键字实现Schema的组合继承，既能复用全局通用字段，又能添加API专属字段。具体实现如下：

1. 定义全局通用Schema #

在components/schemas下定义基础的People模型，包含所有90个通用字段：

components:
  schemas:
    People:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
        # 补充剩余88个通用字段
      required:
        - name
        - age
        # 对应通用字段的必填项

2. 定义扩展后的API专属Schema #

针对Student和Teacher，用allOf将通用People Schema与专属字段合并：

components:
  schemas:
    # 上述People定义保留
    Student:
      allOf:
        - $ref: '#/components/schemas/People'
        - type: object
          properties:
            department_name:
              type: string
            courses_enroled:
              type: array
              items:
                type: string
          required:
            - department_name
    Teacher:
      allOf:
        - $ref: '#/components/schemas/People'
        - type: object
          properties:
            yoe:
              type: integer
              description: 教龄（Years of Experience）
          required:
            - yoe

3. 在API接口中引用对应Schema #

在各POST接口的requestBody里直接引用扩展后的Schema：

paths:
  /api/v1/people:
    post:
      summary: 创建人员信息
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/People'
      responses:
        '201':
          description: 创建成功

  /api/v1/student:
    post:
      summary: 创建学生信息
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Student'
      responses:
        '201':
          description: 创建成功

  /api/v1/teacher:
    post:
      summary: 创建教师信息
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Teacher'
      responses:
        '201':
          description: 创建成功

关键说明 #

• allOf会合并多个Schema的属性，不会出现覆盖问题，最终请求体将包含通用字段与专属字段的全部内容。
• 若需修改通用字段的约束或描述，可在扩展Schema中重新定义该字段，Swagger会优先使用扩展后的规则。

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