Swagger：重用枚举定义作为查询参数

Question

我想使用 definitions 中定义的枚举作为查询字符串中参数定义的一部分。

我在我的 Swagger 2.0 规范文件的 definitions 部分定义了 Swagger 枚举。

OperationType:
  type: string
  enum:
  - registration
  - renewal

我可以在其他定义中创建对它的引用：

Operation:
  type: object
  properties:
    name:
      type: string
    type:
      $ref: '#/definitions/OperationType'

当参数为 in: body 时，我可以使用 schema 标记对其进行引用，但当参数为 in: query

时则不能

    - name: operation
      in: body
      description: description
      schema:
        $ref: '#/definitions/OperationType'

我尝试删除 schema: 并在 enum: 中进行引用，但无法正常工作。

Answer 1

对于 Swagger 2.0，我们限制了将模型定义用于 body 参数以外的任何内容的能力。 definitions 部分用于定义schema，也可以用来定义非对象。但是，只能在使用 schema 关键字的地方访问这些定义。如最初所述，schema 非正文参数不可访问，因此不能被查询或路径参数使用，从而限制了重用这些定义的能力。

有一个 open feature request 要求在规范的未来版本中处理它。

Answer 2

这在 OpenAPI 3.0 中是可能的。所有参数现在都使用 schema，并且通过扩展，可以 $ref 模式。

openapi: 3.0.0
...
paths:
  /something:
    get:
      parameters:
        - in: query
          name: action
          schema:
            $ref: '#/components/schemas/OperationType'
      ...

components:
  schemas:
    OperationType:
      type: string
      enum:
        - registration
        - renewal

Swagger：重用枚举定义作为查询参数

Swagger: Reusing an enum definition as query parameter

swagger

swagger-2.0