Иногда очень удобно вместе с 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
