Swagger: повторное использование определения enum в качестве параметра запроса

Question

Я хотел бы использовать перечисление, определенное в definitions как часть моего определения параметров в строке запроса.

Я определяю Swagger Enum в definitions часть моего файла спецификации Swagger 2.0.

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

Это возможно в 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

Answer 2

Для Swagger 2.0 мы ограничили возможность использовать определения моделей для всего, кроме body параметры. definitions раздел используется для определения схемы, которая также может быть использована для определения не-объектов. Однако эти определения могут быть доступны только там, где schema ключевое слово используется. Как изначально заявлено, schema не доступны для параметров, не связанных с телом, и, как таковые, не могут использоваться параметрами запроса или пути, что ограничивает возможность повторного использования этих определений.

Есть запрос на открытую функцию, требующий его обработки в будущей версии спецификации.