it-swarm.xyz

Может ли Swagger автоматически генерировать свой yaml на основе существующих экспресс-маршрутов?

Я унаследовал существующий API, и я хотел бы задокументировать его со сваггером, но я еще не знаю его полного объема. Может ли Swagger (или другое промежуточное программное обеспечение/инструмент) автоматически генерировать yaml (для swagger) на основе существующих экспресс-маршрутов?

Из того, что я видел по другим вопросам, может показаться, что это в основном ручная работа, но я дважды проверяю, нашел ли кто-то здесь способ обойти это.

36
Manatax

У меня есть опыт автоматической генерации Swagger JSON и написания вручную для API, который я помог построить. Вот плюсы/минусы обоих на основе моего опыта. 

Swagger AUTOMATIC Документация Поколение:

Мы использовали модуль swagger-node-express в сочетании с swagger-ui. https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui

Плюсы

Супер легко документировать. Просто бросьте несколько строк над определением ресурса, и документация (json) будет автоматически сгенерирована модулем. 

Минусы

Вы больше не используете прямой экспресс, когда используете этот пакет. Определения вашего маршрута должны быть определены с помощью модуля Swagger, и это отвлекает вас от Vanilla Express.

Swagger MANUAL Документация Поколение:

Мы просто втянули в проект swagger-ui и написали документацию вручную.
https://github.com/swagger-api/swagger-ui

Плюсы 

Этот подход отделяет документацию от платформы Express. Конечные точки Express пишутся так, как обычно, а документация Swagger определяется отдельно от среды Express. Позволяет писать чистый экспресс.

Минусы 

Изменения в документации становятся немного более утомительными из-за того, что вы вручную пишете и меняете yaml или json. Это немного сложнее, чем просто обновить несколько строк кода над ресурсом. Этот подход также немного более подвержен опечаткам и ошибкам в документации, потому что он полностью печатается вручную.

Если вы планируете вручную написать документацию по swagger, используйте редактор swagger, приведенный ниже, для проверки ваших документов вручную.
http://editor.swagger.io/#/

Заключение

Для этого проекта API мы начали с автоматической генерации документации с использованием пакета swagger-node-express. Тем не менее, мы поняли, что отделение документации Swagger от библиотеки Express важно для того, чтобы мы могли использовать все функции и возможности Express. Я рекомендую вручную писать документы, чтобы иметь полный контроль как над документацией Swagger, так и за веб-платформой Express, которую будет использовать ваше приложение.

45
Mike

Да !!!. Вы можете использовать этот удивительный проект TypeScript-test . Вот пример приложения . Клонируйте его, запустите npm i, npm run swagger и перейдите к /dist/swagger.json. Готово. Swagger yaml и json генерируются на основе экспресс-маршрутов!

2
Dariusz Filipiak

Существует опция: вы можете встроить промежуточное ПО, которое будет анализировать все запросы и ответы и генерировать для вас спецификации: https://github.com/mpashkovskiy/express-oas-generator

Затем вы можете использовать его через пользовательский интерфейс Swagger вашего приложения, например http: // Host: port/api-docs

0
mpashkovskiy