OpenAPI复用同一实体PUT/POST请求定义是否可行？

完全可以实现同一实体PUT和POST请求的定义复用，但你的配置方式存在两个核心问题：一是错误地将包含POST/PUT的完整操作集引用到了两个不兼容的路径上，二是可能存在$ref相对路径的引用错误。以下是具体分析和解决方案：

错误原因分析 #

1. 路径与操作不匹配：
   你把包含POST和PUT的entities同时引用到了/v1/stores/{store_id}/entities（集合路径）和/v1/stores/{store_id}/entities/{entity_id}（单个资源路径），这会导致单个资源路径下也出现POST操作——这不符合REST规范（POST用于创建新资源，不应在URL中指定资源ID），同时会引发参数、请求逻辑的冲突。

2. 引用路径错误：
   构建错误提示找不到updateRequest，本质是requests.yaml中对components.yaml的相对路径基准错误。OpenAPI的$ref相对路径是以引用当前文件的父文件（即service.yaml）为基准，而非当前文件自身位置。如果你的文件结构是根目录下有service.yaml和components.yaml，requests.yaml在v1文件夹内，那么requests.yaml里应该用../components.yaml#/updateRequest而非components.yaml#/updateRequest。

可行解决方案 #

方案一：拆分操作定义，单独引用HTTP方法 #

将POST和PUT操作在requests.yaml中分开定义，然后分别关联到对应路径：

# v1/requests.yaml
createEntity:
  post:
    tags:
      - EntityV1
    operationId: saveEntity
    parameters:
      - $ref: './parameters.yaml#/path/storeId'
    requestBody:
      name: save_config_request
      required: true
      content:
        application/json:
          schema:
            $ref: '../components.yaml#/saveRequest'
    responses:
      200:
        description: save succeeded
        ...

updateEntity:
  put:
    tags:
      - EntityV1
    operationId: updateEntity
    parameters:
      - $ref: './parameters.yaml#/path/storeId'
      - $ref: './parameters.yaml#/path/entityId'
    requestBody:
      name: update_config_request
      required: true
      content:
        application/json:
          schema:
            $ref: '../components.yaml#/updateRequest'
    responses:
      200:
        description: update succeeded
        ...

然后在service.yaml中分别引用：

# service.yaml
paths:
  /v1/stores/{store_id}/entities:
    $ref: './v1/requests.yaml#/createEntity'
  /v1/stores/{store_id}/entities/{entity_id}:
    $ref: './v1/requests.yaml#/updateEntity'

方案二：复用公共组件（更推荐） #

如果POST和PUT存在大量公共逻辑（比如公共参数、响应结构、甚至部分请求体字段），可以将这些公共部分抽到components.yaml中，再在操作里引用，最大化复用：

# components.yaml
components:
  parameters:
    storeId:
      name: store_id
      in: path
      required: true
      schema:
        type: string
    entityId:
      name: entity_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    # 定义公共请求体结构
    BaseEntityRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    saveRequest:
      $ref: '#/BaseEntityRequest'
    updateRequest:
      allOf:
        - $ref: '#/BaseEntityRequest'
        - type: object
          properties:
            lastModified:
              type: string
              format: date-time
  responses:
    EntitySuccess:
      description: 操作成功
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string

然后在requests.yaml中复用这些组件：

# v1/requests.yaml
createEntity:
  post:
    tags:
      - EntityV1
    operationId: saveEntity
    parameters:
      - $ref: '../components.yaml#/components/parameters/storeId'
    requestBody:
      name: save_config_request
      required: true
      content:
        application/json:
          schema:
            $ref: '../components.yaml#/components/schemas/saveRequest'
    responses:
      200:
        $ref: '../components.yaml#/components/responses/EntitySuccess'

updateEntity:
  put:
    tags:
      - EntityV1
    operationId: updateEntity
    parameters:
      - $ref: '../components.yaml#/components/parameters/storeId'
      - $ref: '../components.yaml#/components/parameters/entityId'
    requestBody:
      name: update_config_request
      required: true
      content:
        application/json:
          schema:
            $ref: '../components.yaml#/components/schemas/updateRequest'
    responses:
      200:
        $ref: '../components.yaml#/components/responses/EntitySuccess'

最后在service.yaml中的引用方式和方案一一致即可。

额外提示 #

• 如果saveRequest和updateRequest结构差异极小，可以考虑合并成一个Schema，通过required字段或nullable属性区分必填项，进一步减少冗余。
• 始终遵循REST规范：POST用于集合路径创建资源，PUT用于单个资源路径更新资源，避免操作与路径的不匹配。

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