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

[pOmelchenko]

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

[Evengard]

Вы бы хоть почитали… https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/

[Arbane]

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

[faramozzayw]

Краткость сестра таланта!

[dmitry_dvm]

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

[avigmati]

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

[aleXoid]

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

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