Swagger – умная документация вашего RESTful web-API — обзор Junior back-end developer-а для новичков

Почему swagger, а не его приемник OpenAPI?

>Это был краткий наглядный обзор для начинающих разработчиков API
Суперкраткий

Использую Nswag. В последней версии UI какой-то страшный сделали, старый, который на скринах, намного удобнее.

Команда, в которой я сделал свои первые шаги на поприще написания промышленного кода, разрабатывает, о ужас! апи набирая код, а получившееся описывет в гуглодоках. Клиент вроде как доволен, хотя обратная связь только через лида и в гуглодоке клиенту разрешены только комменты :)

Так и не смог заставить себя полюбить описывать сервисы в Свагере. Конечно, приходится им пользоваться как «индустриальным стандартом», но как-то неприятно это делать. От многих архитекторов слышал схожую брезгливость при работе со сваггером и его “замечательным” swagger-editor.

Очень рекомендую присмотреться к RAML-у. Тулинг вокруг него конечно сильно меньше, но вполне достаточно для описания сервисов, а вот синтаксис прямо в разы более «человеческий». В pet projects уже около года на него перешёл, а вот с командами сложнее, баззворды и «свагерогенераторы» по комментариям/аннотациями и пр. всегда побеждают.