Ответ 1
У меня есть опыт работы с BOTH, который автоматически генерирует Swagger json и вручную записывает его для API, который я помогал в создании. Вот плюсы и минусы обоих, основанные на моем опыте.
Swagger Автоматическое создание документации:
Мы использовали модуль swagger- node -express в сочетании с swagger-ui.
https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Pros
Супер легко документировать. Просто выделите несколько строк над определением ресурса, и документация (json) будет автоматически сгенерирована модулем.
против
Вы больше не используете прямо вверх Express, когда используете этот пакет. Определения маршрутов должны быть определены через модуль Swagger, и это отталкивает вас от ванильного экспресса.
Swagger MANUAL Создание документации:
Мы просто потянули swagger-ui в проект и записали документацию вручную.
https://github.com/swagger-api/swagger-ui
Профи
Этот подход отделяет документацию от платформы Express. Экспресс-конечные точки записываются так, как они обычно записываются, а документация Swagger определяется отдельно от структуры Express. Позволяет писать чистый экспресс.
Против
Изменения в документации становятся немного более утомительными из-за того, что вы вручную пишете и меняете сам yaml или json. Это немного сложнее, чем просто обновление нескольких строк кода над ресурсом. Этот подход также немного более склонен к опечаткам документации и ошибкам из-за того, что он полностью напечатан вручную.
Если вы планируете вручную написать свою документацию по swagger, используйте редактор swagger ниже, чтобы проверить свои документы вручную.
http://editor.swagger.io/#/
Заключение
Для этого проекта API мы начали с автоматической генерации документации с помощью пакета swagger- node -express. Тем не менее, мы поняли, что развязка документации swagger из экспресс-библиотеки имеет важное значение, чтобы мы могли использовать все функции и функциональные возможности Express. Я рекомендую вручную записывать документы, чтобы иметь полный контроль над документацией Swagger и веб-картой Express, которую будет использовать ваше приложение.