OpenAPI - как описать параметры запроса?

Sep 13 2020

Я пытаюсь понять, как задокументировать два параметра моего запроса в OpenAPI.

Фильтрация

Моя фильтрация следует рекомендациям JSON: API , который принимает форму, например:

?filter[post]=1,2,3
?filter[post]=1,2,3&filter[author]=5

filterКлюч ассоциативный массив , который может содержать список имен ресурсов в моем API. Значение, присвоенное каждому ключу фильтра, представляет собой либо один идентификатор, либо список идентификаторов, разделенных запятыми.

Сортировка

Для сортировки также следует рекомендация JSON: API , поэтому что-то вроде этого:

?sort=age
?sort=age,-height

Параметру sortзапроса присваивается значение одного поля сортировки или списка полей сортировки, разделенных запятыми. Обратите внимание, что знак минус перед heightполем указывает на сортировку по убыванию.

Вопрос

Как мне представить свою фильтрацию и сортировку в OpenAPI ?

Например, я не уверен, что могу указать, что ключ фильтра является ассоциативным массивом или что он принимает список идентификаторов, разделенных запятыми. Почти такая же проблема для сортировки: как представить список полей сортировки, разделенных запятыми?

Ответы

DebarghaRoy Sep 24 2020 at 18:13

Приведенный ниже подход должен помочь

parameters:
  - in: query
    name: fields
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: string
        author:
          type: string
  - in: query
    name: sort
    schema:
      type: array
      items:
        type: string
        enum:
          - age
          - height

Отчасти это похоже на вопрос, которым поделился @Helen. Это позволит вам использовать его, как показано на изображении ниже.

И соответствующая команда cURL

curl -X GET "https://editor.swagger.io/user?filter[post]=1,2&filter[author]=3,4&sort=age&sort=height" -H  "accept: */*"

Вы также можете определить filterпараметр следующим образом

parameters:
  - in: query
    name: filter
    style: deepObject
    allowReserved: true
    schema:
      type: object
      properties:
        post:
          type: array
          items:
            type: string
        author:
          type: array
          items:
            type: string

Это приведет к тому, что пользовательский интерфейс станет более полным, как показано ниже.

Тогда запрос cURL выглядит следующим образом

curl -X GET "https://editor.swagger.io/user?filter[post]=1&filter[post]=2&filter[author]=3&filter[author]=4&sort=age&sort=height" -H  "accept: */*"

И вам, вероятно, не нужно, anyOfпоскольку это связано с наследованием в ситуациях, когда метод может возвращать объект базового класса или любого его подкласса.

Обратитесь к спецификации oneof-anyof-allof-not - OpenAPI для получения дополнительной информации.