Документирование ASP .Net Core Web API с помощью OpenAPI/Swagger. Библиотека Swashbuckle

[s207883]

Тег returns тоже можно заполнять, он будет включён в аннотацию ответа.

Про enum и расширения было интересно, спасибо.

[onets]

Эта либа мало того что трудновыговариваемая, так еще и глючнее чем nswag. Из коробки проблемы с версионированными апи. Долбался, долбался - заменил на nswag, все сразу взлетело.

[SSul]

Добрый день! Мы добавили в статью новый раздел «Версионность», где рассказали, как настроить Swagger для работы с разными версиями API

[djnuc]

Только при такой реализации "/{description.GroupName}/" вы все контроллеры из разных групп скинули в одну по имени версии V1, V2, V3 и т.д. Надо немного доработать, чтобы у группы был свой префикс и номер версии "authv1, authv2, goodsv1, salesv1, salesv2". Так же, если у одного контроллера добавится V2, а у другого их не будет, то при префиксном подходе нужно будет ещё отсеять лишние группы, т.к. ApiVersionDescriptions собирается для всего проекта и назначается для каждой группы в не зависимости, есть ли у неё v2 или нет

[Asmera]

Еще эта Люба не умеет документировать классы из nugget пакетов, идущие как параметры в контроллеры (json конечно), что крайне не удобно в единой экосистеме организации, когда часть функций ядра подключается готовыми библиотеками

[binom82]

А как использовать класс SourceHeaders : IOperationFilter ? Не вижу у вас кода с примером.

[SSul]

Добрый день! Подключить фильтр можно в ConfigureServices следующим образом:

services.AddSwaggerGen(options =>
{
options.OperationFilter<SourceHeaders>();
});

[MirrorBoy]

Спасибо за статью.

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

Для .NET Core эта фича лежит в пакете Swashbuckle.AspNetCore.Filters