Как представить посторонние параметры Swagger - PullRequest
Новая
       13

Как представить посторонние параметры Swagger

0 голосов
/ 30 апреля 2018

Наша компания ищет документ Swagger для представления внутреннего сервера.

По разным причинам каждый запрос должен включать серию посторонних параметров заголовка: 

parameters:
    - name: device_id
      in: header
      required: false
      type: string
    - name: ip_address
      in: header
      required: true
      type: string
    - name: client_id
      in: header
      required: true
      type: string
    - name: request_id
      in: header
      required: true
      type: string

Сервер отклонит запрос, если параметры не включены, но сами параметры не связаны с выполняемым запросом.

Основной целью документа Swagger является создание небольшого числа клиентских приложений (все из которых мы контролируем) для взаимодействия с сервером.

Мы могли бы явно добавлять каждый параметр при каждом запросе, но это привело бы к повторению в документе и дополнительной обработке в клиентах. В качестве альтернативы мы могли бы рассматривать эти параметры как метаданные и исключать их из документа, полагаясь на то, что клиенты добавят их в каждый запрос соответствующим образом.

Есть ли рекомендуемый подход для таких параметров?

1 Ответ

0 голосов
/ 30 апреля 2018

Определение OpenAPI служит контрактом между поставщиком API и клиентами. Он может использоваться, помимо прочего, для генерации клиентских SDK . Поэтому ожидается, что определение OpenAPI точно описывает ваш API, включая формат тела запроса, обязательные параметры, аутентификацию и т. Д.

Все обязательные параметры должны быть определены явно.

Чтобы уменьшить дублирование кода, вы можете определить повторно используемые параметры в глобальном разделе parameters (для OpenAPI 2.0) или components/parameters (для OpenAPI 3.0), а затем $ref их из отдельных путей или операций, как показано здесь:
Swagger / OpenAPI - используйте $ ref для передачи повторно используемого определенного параметра

Обратите внимание, что в настоящее время нет способа $ref группы параметров. Соответствующие запросы функций отслеживаются здесь:
Группировка нескольких определений параметров для удобства сопровождения
Глобальные / общие параметры (по какой-то причине он закрыт, хотя и не реализован)

...