Как определить взаимоисключающие параметры запроса в Swagger (OpenAPI)?

Question

У меня есть ряд параметров в Swagger как этот

    "parameters": [ 
        { 
         "name": "username", 
         "description": "Fetch username by username/email", 
         "required": false, 
         "type": "string", 
         "paramType": "query" 
        }, 
        { 
         "name": "site", 
         "description": "Fetch username by site", 
         "required": false, 
         "type": "string", 
         "paramType": "query" 
        }, 
        { 
         "name": "survey", 
         "description": "Fetch username by survey", 
         "required": false, 
         "type": "string", 
         "paramType": "query" 
        } 
       ], 

один параметр должен быть заполнен, но это не имеет значения, один, остальные могут быть оставлены пустыми. Есть ли способ представить это в Swagger?

Answer 1

К сожалению, в настоящее время это невозможно в Swagger. «required» - это просто логическое выражение, и нет возможности представлять взаимозависимости между параметрами.

Лучшее, что вы можете сделать, это прояснить требования в описаниях параметров, а также ввести пользовательское описание 400 Bad Request в тех же строках.

(Там немного обсуждения на https://github.com/swagger-api/swagger-spec/issues/256 о возможных путях реализации этого в следующей версии Swagger)

Answer 2

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

Для меня API, было бы более удобным для использования с тремя конечными точками -как

/user/byName?name= 
/user/bySite?name= 
/user/bySurvey?name= 

Answer 3

В качестве альтернативы можно передать в качестве параметра типа фильтр с перечисления, а значение фильтра со значением для использования.

Пример по адресу: https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

может потребоваться или нет, как вы выберете. Однако, если требуется, они оба должны быть.

Answer 4

Взаимоисключающие параметры возможны (вид) в OpenAPI 3.0:

• Определить взаимоисключающие параметры, как свойства объекта, а также использовать oneOf или maxProperties, чтобы ограничить объект только 1 собственность.
• Используйте parameter serialization methodstyle: form и explode: true, так что объект сериализуется как ?propName=value.

пример использования minProperties и maxProperties ограничения:

openapi: 3.0.0 
... 
paths: 
    /foo: 
    get: 
     parameters: 
     - in: query 
      name: filter 
      required: true 
      style: form 
      explode: true 
      schema: 
      type: object 
      properties: 
       username: 
       type: string 
       site: 
       type: string 
       survey: 
       type: string 
      minProperties: 1 
      maxProperties: 1 
      additionalProperties: false 

Использование oneOf:

 parameters: 
     - in: query 
      name: filter 
      required: true 
      style: form 
      explode: true 
      schema: 
      type: object 
      oneOf: 
       - properties: 
        username: 
        type: string 
       required: [username] 
       additionalProperties: false 
       - properties: 
        site: 
        type: string 
       required: [site] 
       additionalProperties: false 
       - properties: 
        survey: 
        type: string 
       required: [survey] 
       additionalProperties: false 

Другой вариант с использованием oneOf:

 parameters: 
     - in: query 
      name: filter 
      required: true 
      style: form 
      explode: true 
      schema: 
      type: object 
      properties: 
       username: 
       type: string 
       site: 
       type: string 
       survey: 
       type: string 
      additionalProperties: false 
      oneOf: 
       - required: [username] 
       - required: [site] 
       - required: [survey] 

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

Там также открытое предложение в хранилище OpenAPI спецификации к support interdependencies between query parameters поэтому, возможно, будущим версиям спецификации будет иметь лучший способ определить такие сценарии.