Web API: автодокументация (Help Page / Swagger)

Иногда очень удобно вместе с API иметь страницу показывающую реализованные в данный момент интерфейсы/методы и модели

При создании Web API проекта из VS 2015 в настоящий момент предлагается ASP.NET Web API Help Page, и работает решение практически из коробки
Необходимо лишь решить - нужны ли комментарии к методам и свойствам моделей

Но в ASP .NET Web API Help Page есть существенные недостатки:
  • методы можно посмотреть, но нельзя вызвать тут же
  • для генерации моделей для PATCH требовались дополнительные телодвижения, например через метод SetSampleForType, а хочется всё же - большей гибкости (создал метод/модель - пользователи тут же могут её увидеть)
  • Когда бизнес-логика и модели отделены от Web API (собственно контракты/модели в одной библиотеке, а модели в другой, web api - в третьей) help pages не даёт возможности указать несколько XML-документов. Как следствие - необходимо их смёржить, а после - указывать базовый
  • Слишком много телодвижений (переходов меж страницами)
  • Нельзя указать список возвращаемых HTTP-кодов
т.е. получается вроде бы как результат есть, но что-то не то

Swagger же лишён всех этих недостатков
Проявил себя в самом лучшем виде и уже несколько месяцев после начальной настройки под себя - мы его боле не трогали (проект немного специфичный, необходимо иметь возможность отправлять кастомные http-заголовки).

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

Тем не менее сначала рассмотрим краткую инструкцию о том, как создать ASP .NET API Help Page, а после - перейти на Swagger

И если нужны комментарии к методам/моделям, то
  1. Идём в свойства проекта
  2. Выбираем вкладку Build
  3. Ставим флажок XML  documentation file
  4. Указываем путь App_Data\WebApiAutoDoc.xml
  5. Находим файл HelpPageConfig.cs и прописываем наш XML в метод SetDocumentationProvider
  6. После этого необходимо оставить XML-комментарии на Web API методах и в используемых ими моделях
т.е. примерно так: 

Должен получиться примерно следующий список контроллеров и их методов:

При клике на метод GET api/Account/UserInfo - будет произведён переход на просмотр входной/выходной моделей:

Стоит заметить, что enum значения по дефолту возвращаются как целые числа
Если необходимо возвращать строки, то достаточно повесить атрибут [JsonConverter(typeof(StringEnumConverter))] на enum-свойство:

В любом случае - отправлять запросы нельзя

Теперь рассмотрим Swagger
Он также использует XML-комментарии, так что - то что было сделано оставляем на месте

Необходимо установить Swashbuckle: Install-Package Swashbuckle
Или через NuGet Package Manager: 


После успешной установки можно переходить на swagger/ui/index


Четыре минуса ASP .NET API Help Page отсутствуют в swagger из коробки

Остаётся прописать XML-документацию

Для этого открываем файл App_Start/SwaggerConfig.cs
Добавляем метод для определения комментариев к сборке:

Предполагается, что имя файла комментариев совпадает с названием сборки

После компилим, запускаем, наблюдаем:
Комментарии появились и у метода, и у свойств
Учитывая то, что Swagger методом IncludeXmlComments позволяет указывать множество файлов для комментариев - он абсолютно обгоняет стандартный дефолтный механизм

Для тех, у кого ещё используются cookies для авторизации (или чего ещё) - будет удобен, при тестировании с использованием авторизации

Прошу заметить, что Enum по дефолту представлен числовыми значениями
Можно, конечно, настроить использование аттрибута JsonConverter, для того, чтобы продолжать самостоятельно указывать, где должно быть число, а где - строка, но ввиду того, что клиентам, как правило, нужна именно строка (если enum не флаги, конечно), то swagger предлагает все Enum передавать как строки:


Также у swagger есть API, позволяющий вмешиваться в отправку запроса на сервер, например при необходимости отправить кастомные http-заголовки
Но об этом немного в следующий раз

Со скрина сверху видно, что метод возвращает при статусе 200 OK модель из четырёх полей
Для указания иных HTTP-статусов и их моделей необходимо использовать атрибут SwaggerResponse, который принимает в качестве параметров:
  1. statusCode - перечисление System.Net.HttpStatusCode
  2. description - строка, для человеческого описания
  3. type - тип возвращаемой модели
Для статуса 200 OK параметр type по умолчанию инициируется возвращаемым значением

А вот и пример:

Комментариев нет:

Отправка комментария

Можете оставить свой комментарий