Swagger ui - 从组件调用参数

Question

我将 swagger ui 与 swaggerapi/swagger-ui docker 映像一起使用。我尝试在其中一个路径中使用组件中定义的参数，但这不起作用。问题出在哪里？

在我的 index.yaml 文件中

components:
  ...
  parameters:
    Pagination:
    - in: query
      name: page
      schema:
        type: integer
        required: false
      description: The page to go to
    - in: query
      name: per_page
      schema:
        type: integer
        required: false
      description: The number of items per page
  ...

在我的路径文件中

parameters:
  $ref: '../index.yaml#/components/parameters/Pagination'

感谢您的帮助

Answer 1

OpenAPI 允许您$ref 单个参数，而不是一组参数。因此，如果您有多个常用参数，则需要在 components/parameters 部分中为它们创建单独的定义。此外，required 是参数属性，而不是架构属性：

components:
  parameters:
    pageParam:          # <-----
      in: query
      name: page
      schema:
        type: integer
      required: false   # <-----
      description: The page to go to
    perPageParam:       # <-----
      in: query
      name: per_page
      schema:
        type: integer
      required: false   # <-----
      description: The number of items per page

然后，在你的路径文件中，使用：

parameters:
  - $ref: '../index.yaml#/components/parameters/pageParam'
  - $ref: '../index.yaml#/components/parameters/perPageParam'