Swagger peut-il générer automatiquement son yaml à partir des itinéraires express existants?
J'ai hérité d'une API existante et j'aimerais la documenter avec swagger, mais je n'en connais pas encore la portée. Swagger (ou un autre middleware/outil) peut-il générer automatiquement le yaml (pour swagger) par magie en fonction des itinéraires express existants?
D'après ce que j'ai vu sur d'autres questions, il semblerait qu'il s'agisse principalement d'un travail manuel, mais je vérifie si quelqu'un ici a trouvé une solution.
J'ai de l'expérience dans la génération automatique de Swagger json et l'écriture manuelle pour une API que j'ai aidé à construire. Voici les avantages/inconvénients des deux sur la base de mon expérience.
Génération de documentation Swagger AUTOMATIC:
Nous avons utilisé le module swagger-node-express en combinaison avec swagger-ui. https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Avantages
Super facile à documenter. Jetez quelques lignes au-dessus de la définition de la ressource et la documentation (json) est automatiquement générée par le module.
Les inconvénients
Vous n'utilisez plus straight up Express lorsque vous utilisez ce package. Les définitions de votre itinéraire doivent être définies via le module Swagger, ce qui vous éloigne de Vanilla Express.
Génération de documentation MANUELLE Swagger:
Nous venons d’intégrer swagger-ui dans le projet et d’écrire la documentation manuellement.
https://github.com/swagger-api/swagger-ui
Avantages
Cette approche permet de découpler la documentation du framework Express. Les points de terminaison Express sont écrits comme ils le seraient normalement et la documentation Swagger est définie séparément du cadre Express. Vous permet d'écrire purement express.
Les inconvénients
Les modifications de la documentation deviennent un peu plus fastidieuses du fait que vous écrivez et changez vous-même manuellement yaml ou json. C'est un peu plus difficile que de mettre à jour quelques lignes de code au-dessus d'une ressource. Cette approche est également un peu plus sujette aux fautes de frappe et aux erreurs de documentation car elle est entièrement saisie manuellement.
Si vous prévoyez d'écrire manuellement votre documentation swagger, utilisez l'éditeur swagger ci-dessous pour valider votre documentation manuelle.
http://editor.swagger.io/#/
Conclusion
Pour ce projet d'API, nous avons commencé par générer automatiquement la documentation à l'aide du package swagger-node-express. Cependant, nous avons réalisé que le découplage de la documentation de swagger de la bibliothèque Express était important pour nous permettre d'utiliser toutes les fonctionnalités d'Express. Il est recommandé d’écrire manuellement la documentation pour avoir le plein contrôle de la documentation Swagger et du framework Web Express que votre application utilisera.
Oui !!! Vous pouvez utiliser ce projet génial TypeScript-test . Voici exemple d'application . Clonez-le, lancez npm i, npm run swagger et accédez à /dist/swagger.json. Terminé. Swagger yaml et json est généré à partir d’itinéraires express!
Il existe une option: vous pouvez intégrer un middleware qui analysera toutes les demandes et réponses et générera une spécification pour vous: https://github.com/mpashkovskiy/express-oas-generator
Ensuite, vous pouvez l’utiliser via l’interface utilisateur de votre application Swagger comme http: // Host: port/api-docs