Я унаследовал существующий API, и я хотел бы документировать его с помощью swagger, но я пока не знаю его полного объема. Может ли Swagger (или другое промежуточное программное обеспечение/инструмент) автоматически создавать магические символы yaml (для swagger) на основе существующих экспресс-маршрутов?
Для того, что я видел по другим вопросам, казалось бы, это в основном ручная работа, но я дважды проверяю, нашел ли кто-нибудь этот способ.
У меня есть опыт работы с BOTH, который автоматически генерирует Swagger json и вручную записывает его для API, который я помогал в создании. Вот плюсы и минусы обоих, основанные на моем опыте.
Мы использовали модуль 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-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, которую будет использовать ваше приложение.
Да!!!. Вы можете использовать этот удивительный проект typescript -test. Вот пример приложения. Скройте его, запустите npm i, npm run swagger и перейдите в /dist/swagger.json. Готово. Swagger yaml и json генерируются на основе экспресс-маршрутов!
Существует опция: вы можете вставлять промежуточное программное обеспечение, которое будет анализировать все запросы и ответы и генерировать спецификации для вас: https://github.com/mpashkovskiy/express-oas-generator p >
Затем вы можете использовать его через приложение Swagger UI, например http://host:port/api-docs