能否在components/schema外放置可复用组件？非Model类复用组件咨询

首先明确：OpenAPI规范并没有强制要求所有可复用结构都必须放在components/schemas里，我们可以根据需求选择不同的组织方式，同时兼顾规范兼容性和代码可读性。

方案一：用components/schemas+自定义扩展标记（推荐，兼容性拉满） #

如果不想把这些复用片段当作正式的"Model"，可以给它们加上自定义的扩展字段（比如x-is-partial: true）来做区分。这种方式既完全符合OpenAPI规范，所有支持规范的工具都能正常识别$ref引用，又能清晰区分哪些是业务Model，哪些是复用片段。

示例代码：

components:
  schemas:
    # 这是正式的业务Model
    User:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        username:
          type: string
    
    # 下面是你的partial复用片段，带扩展标记
    NotFoundError:
      x-is-partial: true
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 404
        message:
          type: string
          example: "Resource Not Found"
    ID-Array:
      x-is-partial: true
      type: array
      items:
        $ref: '#/components/schemas/ID'
      writeOnly: true
    ID:
      x-is-partial: true
      type: integer
      format: int32
      example: 1

方案二：自定义components子节点（结构清晰，但需注意工具兼容性） #

如果你想从结构上彻底把partial和正式Model分开，可以在components下创建自定义的子节点（比如partials），把复用片段放在这里。这种方式不属于OpenAPI官方规范的一部分，但很多现代工具（比如自定义的文档生成器、API网关）只要支持自定义扩展，就能正常识别。

示例代码：

components:
  schemas:
    # 正式业务Model
    User:
      type: object
      properties:
        id:
          $ref: '#/components/partials/ID'
        favoriteIds:
          $ref: '#/components/partials/ID-Array'
    
    # 自定义的partial节点
    partials:
      NotFoundError:
        type: object
        properties:
          code:
            type: integer
            format: int32
            example: 404
          message:
            type: string
            example: "Resource Not Found"
      ID-Array:
        type: array
        items:
          $ref: '#/components/partials/ID'
        writeOnly: true
      ID:
        type: integer
        format: int32
        example: 1

方案三：针对特定语义的片段用对应预定义节点 #

比如你的NotFoundError是响应结构，其实更适合放在components/responses里，这完全符合OpenAPI的语义设计，也能自然复用：

components:
  responses:
    NotFoundError:
      description: 请求的资源不存在
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                format: int32
                example: 404
              message:
                type: string
                example: "Resource Not Found"

后续在路径里引用时直接用$ref: '#/components/responses/NotFoundError'即可，语义更清晰。

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