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 по умолчанию инициируется возвращаемым значением

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