如何在OpenAPI文件中为同一操作声明多路径端点并避免重复？

针对你提到的OneDrive文件签入操作这类多路径复用同一逻辑的场景，完全可以通过OpenAPI的**引用机制（$ref）**来避免重复编写冗余内容，核心思路是把操作的通用逻辑（请求体、响应、摘要描述等）提取到统一位置，再在各个路径下引用，仅保留每个路径独有的参数定义。

具体实现步骤 #

1. 提取通用操作定义
   把签入操作的核心逻辑（比如请求体结构、响应模型、操作摘要等）放到components.operations中，作为可复用的模板：

components:
  # 先定义通用参数（可选，进一步减少冗余）
  parameters:
    itemIdParam:
      name: itemId
      in: path
      required: true
      schema:
        type: string
  # 定义通用的签入操作逻辑
  operations:
    checkinDriveItem:
      tags:
        - 驱动器文件操作
      summary: 签入已签出的文件
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: 签入时的备注信息
                checkInAs:
                  type: string
                  enum: [minor, major]
                  description: 签入版本类型（次要版本/主要版本）
      responses:
        '200':
          description: 签入成功，返回更新后的文件信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItem'
        '400':
          description: 请求参数不合法
        '404':
          description: 目标文件不存在或无权访问

2. 在各路径下引用通用操作
   每个路径只需要声明自身独有的路径参数，然后通过$ref复用上面定义的通用操作逻辑：

paths:
  /drives/{driveId}/items/{itemId}/checkin:
    post:
      $ref: '#/components/operations/checkinDriveItem'
      parameters:
        - name: driveId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/itemIdParam'

  /groups/{groupId}/drive/items/{itemId}/checkin:
    post:
      $ref: '#/components/operations/checkinDriveItem'
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/itemIdParam'

  /me/drive/items/{itemId}/checkin:
    post:
      $ref: '#/components/operations/checkinDriveItem'
      parameters:
        - $ref: '#/components/parameters/itemIdParam'

  /sites/{siteId}/drive/items/{itemId}/checkin:
    post:
      $ref: '#/components/operations/checkinDriveItem'
      parameters:
        - name: siteId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/itemIdParam'

  /users/{userId}/drive/items/{itemId}/checkin:
    post:
      $ref: '#/components/operations/checkinDriveItem'
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/itemIdParam'

注意事项 #

• 该方案兼容OpenAPI 3.0及以上版本，3.1版本对引用的支持更加灵活（允许在更多位置使用$ref）；
• 所有路径复用同一操作逻辑，仅差异部分（路径参数）单独声明，既保证了OpenAPI文件的简洁性，又能清晰体现每个端点的路径结构；
• 服务器端可自行解析这些路径变体，无需额外处理OpenAPI层面的复用逻辑。

内容的提问来源于stack exchange，提问作者Eugene Mayevski 'Callback