我们可以在 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 不支持覆盖引用参数的 name。这是 OpenAPI 规范存储库中的相关功能请求：
Extend/override properties of a parameter

但是，在 OpenAPI 3.1 中，可以覆盖引用参数的 description：

# 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'   # <-----

Answer 2

我想 allOf 可以在参数架构中使用，如下所示。

allOf 只能在模式对象中使用。并且由于 parameters，paths 可能包含 schema 个对象 allOf 可以在参数中使用，如下所示。

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

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

Can we use allOf in OpenAPI /components/parameters to override attributes of a referenced parameter?

openapi

swagger-editor