Kann Swagger sein yaml basierend auf vorhandenen Expressrouten automatisch generieren?
Ich habe eine bestehende API geerbt und möchte sie mit swagger dokumentieren, weiß aber noch nicht den vollen Umfang davon. Kann Swagger (oder ein anderes Middleware/Tool) das yaml (für Swagger) automatisch auf der Grundlage der vorhandenen Expressrouten generieren?
Für das, was ich bei anderen Fragen gesehen habe, scheint es sich hier hauptsächlich um einen manuellen Job zu handeln, aber ich überprüfe noch einmal, ob jemand hier einen Ausweg gefunden hat.
Ich habe Erfahrung darin, den Swagger-Json automatisch zu generieren und manuell für eine API aufzuschreiben, die ich beim Erstellen unterstützt habe. Hier sind die Vor- und Nachteile beider basierend auf meiner Erfahrung.
Swagger AUTOMATIC Dokumentationserstellung:
Wir haben das Swagger-Node-Express-Modul in Kombination mit Swagger-UI verwendet. https://www.npmjs.com/package/swagger-node-express
https://github.com/swagger-api/swagger-ui
Pros
Super einfach zu dokumentieren. Werfen Sie einfach ein paar Zeilen über die Ressourcendefinition und die Dokumentation (Json) wird automatisch vom Modul generiert.
Cons
Sie verwenden nicht mehr direkt Express, wenn Sie dieses Paket verwenden. Ihre Streckendefinitionen müssen über das Swagger-Modul definiert werden. Dadurch werden Sie von Vanilla Express abgezogen.
Swagger MANUAL Dokumentationserstellung:
Wir haben gerade swagger-ui in das Projekt hineingezogen und die Dokumentation manuell geschrieben.
https://github.com/swagger-api/swagger-ui
Pros
Dieser Ansatz entkoppelt die Dokumentation vom Express-Framework. Express-Endpunkte werden so geschrieben, wie sie normalerweise geschrieben würden, und die Swagger-Dokumentation wird separat vom Express-Framework definiert. Erlaubt Ihnen, reinen Ausdruck zu schreiben.
Cons
Dokumentationsänderungen werden etwas langweiliger, da Sie das yaml oder json selbst manuell schreiben und ändern. Es ist etwas schwieriger, als nur ein paar Zeilen Code über einer Ressource zu aktualisieren. Dieser Ansatz ist auch etwas anfälliger für Dokumentationsfehler und -fehler, da er vollständig manuell eingegeben wird.
Wenn Sie planen, Ihre Swagger-Dokumentation manuell zu schreiben, verwenden Sie den untenstehenden Swagger-Editor, um Ihre manuellen Dokumente zu überprüfen.
http://editor.swagger.io/#/
Fazit
Für dieses API-Projekt haben wir zunächst die Dokumentation mit dem Paket swagger-node-express automatisch generiert. Wir haben jedoch erkannt, dass die Entkopplung der Swagger-Dokumentation von der Express-Bibliothek wichtig ist, damit wir alle Funktionen und Funktionen von Express nutzen können. Ich empfehle, die Dokumente manuell zu schreiben, um sowohl die Swagger-Dokumentation als auch das von Ihrer App verwendete Express-Web-Framework vollständig steuern zu können.
Ja !!!. Sie können dieses großartige Projekt TypeScript-test verwenden. Hier ist Beispiel App . Klonen Sie es, führen Sie npm i, npm run swagger aus und gehen Sie zu /dist/swagger.json. Erledigt. Swagger Yaml und Json wird auf der Grundlage von Expressrouten generiert!
Es gibt eine Option: Sie können Middleware einbetten, die alle Anfragen und Antworten analysiert und Spezifikationen für Sie generiert: https://github.com/mpashkovskiy/express-oas-generator
Dann können Sie es über Ihre App Swagger-Benutzeroberfläche verwenden, wie http: // Host: Port/api-docs