Как определить путь с двумя необязательными параметрами в OpenAPI 3.0? - PullRequest
Новая
       29

Как определить путь с двумя необязательными параметрами в OpenAPI 3.0?

1 голос
/ 15 февраля 2020

Я зарегистрировался на SwaggerHub и создал новый API, используя OpenAPI 3.0. В моем API путь /tasks имеет 2 необязательных параметра, но я не могу установить их как необязательные - редактор показывает ошибку «Недопустимые значения».

Вот мое определение API: 

openapi: 3.0.0
info:
  description: A Simple IP Address API
  title: VTasks
  version: v1
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/petrogromovo/Vtasks/1.0.0
  - description: SwaggerHub API Auto Mocking
    url: http://hosting.tk

paths:

  /tasks:
    get:
      tags:
        - tasks
      summary: Get paginated / filtered tasks listing
      operationId: tasks
      parameters:
        - name: page
          in: path
          description: The page number to be fetched. If missed default 1.
          required: true
          schema:
            type: integer
        - name: order_by
          in: path
          description: The order_by  be fetched. 
          required: false  // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
        - name: filter
          in: path
          description: The filter for title field. 
          required: false // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Invalid tasks supplied
        '404':
          description: tasks were not found

Но если я удаляю атрибуты required, я получаю 2 ошибки:

должно иметь обязательное свойство 'required'
missingProperty: обязательно

Какой правильный синтаксис?

1 Ответ

1 голос
/ 16 февраля 2020

Предполагается ли, что эти параметры являются параметрами пути или параметрами запроса?

Параметры пути (in: path) являются частью пути конечной точки, и поэтому должны указываться {...} в шаблоне пути: 

paths:
  /tasks/{page}/{order_by}/{filter}:

Параметры пути всегда требуются, т.е. они должны иметь required: true.

Параметры запроса отправляются в строке запроса, например /tasks?page=...&order_by=.... Чтобы использовать параметры запроса, измените местоположение параметра на in: query.

Дополнительная информация: Описание параметров

...