如何使用单独文件中描述的openapi“参数”部分？

Question

我使用openapi v3.0.3

我有3个参数

- name: query
  in: query
  description: ''
  required: false
  schema:
    type: string
- name: limit
  in: query
  description: ''
  required: false
  schema:
    type: integer
- name: offset
  in: query
  description: ''
  required: false
  schema:
    type: integer

在某些情况下，我只想使用

query

，在其他情况下 - 想要使用所有这些：

query

、

limit

和

offset

。我想要 3 个不同的文件：“query.yaml”、“pagination.yaml”和

query_with_pagination.yaml

，以便能够将其包含在我需要的地方。例如：

parameters:
  - $ref: '../../shared/parameters/query.yaml'

或

parameters:
  - $ref: '../../shared/parameters/query_with_pagination.yaml'

我该怎么做？

（

paramters: - allOf: ....

不起作用，因为“应该有属性

in

”）

Answer 1

在 OpenAPI 3.x 中，我们只能引用单个参数，而不能引用一组参数。 （这可能会在 v4“Moonwalk”中改变。）

假设您将参数定义保存在两个文件中：

query.yaml

：

name: query
in: query
description: ''
required: false
schema:
  type: string

pagination.yaml

：

limit:
  name: limit
  in: query
  description: ''
  required: false
  schema:
    type: integer

offset:
  name: offset
  in: query
  description: ''
  required: false
  schema:
    type: integer

您可以单独引用

query

参数：

parameters:
  - $ref: '../../shared/parameters/query.yaml'

并将

query

和分页参数引用为：

parameters:
  - $ref: '../../shared/parameters/query.yaml'
  - $ref: '../../shared/parameters/pagination.yaml#/limit'
  - $ref: '../../shared/parameters/pagination.yaml#/offset'