node.js - adding - swagger-node-express
¿Puede Swagger autogenerar su yall basándose en rutas exprés existentes? (3)
Existe una opción: puede incorporar middleware que analizará todas las solicitudes y respuestas y generará especificaciones para usted: https://github.com/mpashkovskiy/express-oas-generator
Luego puede usarlo a través de la aplicación Swagger UI como http://host:port/api-docs
Heredé una API existente y me gustaría documentarla con arrogancia, pero todavía no conozco su alcance completo. ¿Puede Swagger (u otro middleware / herramienta) generar automáticamente el yaml (para swagger) basado en las rutas exprés existentes?
Por lo que vi en otras preguntas, parece que este es principalmente un trabajo manual, pero estoy comprobando si alguien aquí encontró una forma de evitar esto.
Tengo experiencia tanto en la generación automática de swagger json como en la escritura manual de una API que ayudé a compilar. Aquí están los pros / contras de ambos basados en mi experiencia.
Swagger AUTOMATIC Documentation Generation:
Usamos el módulo swagger-node-express en combinación con swagger-ui. https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Pros
Súper fácil de documentar. Solo arroje unas líneas arriba de la definición del recurso y la documentación (json) es generada automáticamente por el módulo.
Contras
Ya no usa Express cuando usa este paquete. Las definiciones de ruta deben definirse a través del módulo Swagger y esto lo aleja de vanilla Express.
Generación de documentación MANUAL de Swagger:
Acabamos de llamar a swagger-ui al proyecto y escribimos la documentación de forma manual.
https://github.com/swagger-api/swagger-ui
Pros
Este enfoque desacopla la documentación del marco Express. Los puntos finales expresos se escriben como normalmente se escribirían y la documentación de Swagger se define por separado del marco expreso. Le permite escribir pure express.
Contras
Los cambios en la documentación se vuelven un poco más tediosos debido a que usted está escribiendo y cambiando el yaml o json manualmente. Es un poco más difícil que simplemente actualizar algunas líneas de código encima de un recurso. Este enfoque también es un poco más propenso a errores tipográficos y errores de documentación debido al hecho de que está completamente tipeado manualmente.
Si planea escribir manualmente su documentación swagger, utilice el editor swagger a continuación para validar sus documentos manuales.
http://editor.swagger.io/#/
Conclusión
Para este proyecto API, comenzamos generando automáticamente la documentación usando el paquete swagger-node-express. Sin embargo, nos dimos cuenta de que desacoplar la documentación swagger de la biblioteca express era importante para permitirnos usar todas las funciones y funcionalidades de Express. Recomiendo escribir los documentos manualmente para tener control total sobre la documentación de Swagger y el marco web Express que usará tu aplicación.
¡Sí! . Puedes usar este impresionante proyecto typescript-test . Aquí hay una aplicación de ejemplo . npm i , ejecutar npm i , npm run swagger e ir a /dist/swagger.json . Hecho. ¡Swagger yaml y json se generan en base a rutas exprés!