На днях возникла потребность вывести в OpenAPI спецификации сразу 2 варианта ответа от API для одного статус кода.
К примеру, API может вернуть 200ый статус с application/problem+json или application/json.
Это полезно для генераторов клиентов, чтобы они корректно обрабатывали разные кейсы ответов.
На рабочих проектах я использую ProblemDetails для ответов с ошибками и application/json для успешных ответов.
И OpenAPI спецификация к счастью позволяет задать для разных Content-Type свои варианты ответов с примером для каждого статус кода. Пример спеки 'https://t.me/sh_dotnet/126?comment=479' rel='nofollow'>см. в комментариях.
На текущий момент я не пишу спеку вручную, а использую популярный генератор Swashbuckle. И реализовывав IOperationFilter можно по-своему доработать генерацию спеки.
В моем случае при обнаружении нескольких атрибутов SwaggerResponseAttribute на один статус код я генерирую ему схему, пример и добавляю в описание текущего API.
Результаты на скриншотах
Полезные ссылки:
* Пример
* RFC ProblemDetails
К примеру, API может вернуть 200ый статус с application/problem+json или application/json.
Это полезно для генераторов клиентов, чтобы они корректно обрабатывали разные кейсы ответов.
На рабочих проектах я использую ProblemDetails для ответов с ошибками и application/json для успешных ответов.
И OpenAPI спецификация к счастью позволяет задать для разных Content-Type свои варианты ответов с примером для каждого статус кода. Пример спеки 'https://t.me/sh_dotnet/126?comment=479' rel='nofollow'>см. в комментариях.
На текущий момент я не пишу спеку вручную, а использую популярный генератор Swashbuckle. И реализовывав IOperationFilter можно по-своему доработать генерацию спеки.
В моем случае при обнаружении нескольких атрибутов SwaggerResponseAttribute на один статус код я генерирую ему схему, пример и добавляю в описание текущего API.
Результаты на скриншотах
Полезные ссылки:
* Пример
* RFC ProblemDetails