Комментарии 10
Вы используете это чисто для документирования? Мне интересно какие гарантии, что реализация в коде соответствует описанному в swagger и как это проверить.
Совершенно правильный вопрос. При изменении вашего кода обычно сильно некогда/лень/забыл обновлять документацию и она стремительно устаревает. Меня приводит в дикий восторг @nestjs/swagger именно тем, что ты 1 раз пишешь исполняемый код, а актуальная документация (в основном полная) генерится автоматически без всяких стрёмных комментариев. Но нест это несколько другая история
У нас используется подход API-First, когда сначала проектируем схемы, а уже потом пишем реализацию в коде. Есть мысли про контрактные тесты - где сравнивается исходная схема с автогенерируемой приложением. Но с инструментами пока не понятно.
неистово плюсую @nestjs/swagger )))
поддерживать спеку и соответствующий код - та еще задача, как вариант, если у вас spec first, писать спеку, затем писать код, по которому генерится спека и сверять их на соответствие друг другу.
до nestjs пользовался express-openapi, там в коде дополняешь объекты и по ним потом соответствующая swagger spec генерится, описание лежит рядом с кодом. удобно, как пример https://github.com/antirek/sonata/tree/master/api/manage
swagger-autogen многое умеет определять автоматически (конечные точки, параметры и тела запросов в общем виде, статус-коды ответов и т.д.). Понятно, что чем более подробное описание, тем сильнее оно подвержено устареванию (потому что подробное описание делается вручную). Вероятно, на этапе активной разработки приложения основное внимание следует уделять поддержанию в актуальном состоянии хотя бы основного описания с помощью doc (модели, операции и т.п.), а подробными комментариями снабжать только относительно стабильные роуты
Большое спасибо за данную статью - давно хотел в этом разобраться, но вся информация в сети как-то разрознена. Здесь собрано все самое нужное. Побежал пробовать. Еще не помешала бы ссылочка на спецификацию комментариев в роутах.
Не за что. Спецификация комментариев, как вы это называете, имеется в документации к swagger-autogen, начиная отсюда: https://github.com/davibaltar/swagger-autogen#endpoints
Пробовал в прошлом году swagger, но что-то у меня с ним не вышло. Всё равно прописывать всё, так или в комментариях. Надо углубиться.
Как увидел redoc, сразу на него перешли. Понимает спецификации в yaml и json
Node.js: документирование и визуализация API с помощью Swagger