openapi - 我们可以在 OpenAPI/components/parameters 中使用 allOf 来覆盖引用参数的属性吗？

Question

我尝试使用 OpenAPI 3 创建 API 文档，但当我尝试在参数定义中使用 allOf 关键字时出现错误:

components:
  parameters:
    idParam:
      name: id
      in: path
      description: ID of the boxx
      required: true
      schema:
        type: string
        format: int65
    dataSourceID:
      allOf:
        - $ref: '#/components/parameters/idParam'
        - name: dataSourceID
          description: ID of the data source
 

Schema error at components.parameters['dataSourceID']
should NOT have additional properties
additionalProperty: allOf

是否可以重用另一个参数的值？也许以不同的方式？

Answer 1

OpenAPI 不支持覆盖引用参数的名称。以下是 OpenAPI 规范存储库中的相关功能请求:
Extend/override properties of a parameter

但是，在 OpenAPI 3.1 中，可以覆盖引用参数的描述:

# openapi: 3.1.0

components:
  parameters:
    ...

    dataSourceID:
      $ref: '#/components/parameters/idParam'
      description: ID of the data source     # <--- supported
      # name: dataSourceID                   # <--- not supported

在您的示例中，您最多可以为 int65 定义可重用架构并从两个参数引用它:

openapi: 3.0.0
...

components:
  schemas:
    int65:
      type: string
      format: int65

  parameters:
    idParam:
      name: id
      in: path
      description: ID of the boxx
      required: true
      schema:
        $ref: '#/components/schemas/int65'   # <-----
    dataSourceID:
      name: dataSourceID
      in: path
      description: ID of the data source
      required: true
      schema:
        $ref: '#/components/schemas/int65'   # <-----