Question

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

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

OperationType:
  type: string
  enum:
  - registration
  - renewal

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

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

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

时对其进行引用

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

我尝试删除schema:并在enum:中引用，但无法使其生效。

Answer 1

对于Swagger 2.0，我们限制了将模型定义用于除BackgroundWorker参数之外的任何内容的能力。 body部分用于定义模式，该模式也可用于定义非对象。但是，只能在使用definitions关键字的情况下访问这些定义。如上所述，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：将枚举定义重用为查询参数

2 个答案: