Форс; укажите два ответа с одинаковым кодом на основе необязательного параметра

Этот вопрос не является дубликатом (Swagger - укажите необязательное свойство объекта или несколько ответов), поскольку этот OP пытался вернуть 200 или 400.

У меня есть GET с необязательным параметром; например, GET/endpoint?selector=foo.

Я хочу вернуть 200, чья схема отличается в зависимости от того, был ли передан параметр, например:

GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah  -> {200, schema_2}

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

Есть ли способ сделать это?

Изменение: следующее кажется связанным: https://github.com/OAI/OpenAPI-Specification/issues/270

ОТВЕТЫ

Ответ 1

OpenAPI 3.0 позволяет использовать oneOf для определения нескольких возможных тел запросов или тел ответов для одной и той же операции:

openapi: 3.0.0
...
paths:
  /path:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'

Однако невозможно сопоставить конкретные схемы ответов с конкретными значениями параметров. Вам необходимо будет устно документировать эти особенности в description ответа, операции и/или параметра.

Вот, возможно, связанный запрос улучшения:
Разрешить перегрузку объекта с помощью get- ^ post- ^ и т.д.


Примечание для пользователей пользовательского интерфейса Swagger: На момент написания этой статьи (декабрь 2018 г.) пользовательский интерфейс Swagger не генерирует автоматически примеры для схем oneOf и anyOf. Вы можете следить за этой проблемой для получения обновлений.

В качестве обходного пути вы можете указать ответ example или examples вручную. Обратите внимание, что для использования нескольких examples требуется Swagger UI 3.23. 0+ или Swagger Editor 3.6. 31+.

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'
              example:   # <--------
                foo: bar

Ответ 2

Мне нужно то же самое, и я придумал обходное решение, которое, похоже, работает:

Я только что определил два разных пути:

/path:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseOne'
(...)

/path?parameter=value:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseTwo'
(...)

Пути работают с редактором swagger. Я могу даже документировать каждую опцию по-разному и добавлять необязательные параметры, которые могут быть только во втором случае, чтобы сделать, чтобы документ API был намного чище. Используя operationId, вы можете создавать более чистые имена для сгенерированных методов API.

Я разместил здесь одно и то же решение (https://github.com/OAI/OpenAPI-Specification/issues/270), чтобы проверить, нет ли чего-то большего.

Я понимаю, что это явно не разрешено/не рекомендуется делать (ни я не нашел места, явно запрещающего его). Но в качестве обходного пути и единственного способа документировать API с таким поведением в текущей спецификации выглядит как опция.

Две проблемы, с которыми я об этом узнал:

  • URL-адрес кода Java кода ускоряет знак "=", поэтому он не работает, если вы исправляете это в сгенерированном коде. Вероятно, это происходит в другом коде генераторы.
  • Если у вас есть дополнительные параметры запроса, он добавит дополнительные "?" и не работает;

Если это не блокирующие устройства, это, по крайней мере, позволит вам правильно документировать такие случаи и разрешать тестирование с помощью редактора swagger.