swagger Tutorial
Erste Schritte mit Swagger
Suche…
Bemerkungen
In diesem Abschnitt erhalten Sie einen Überblick darüber, was Swagger ist und warum ein Entwickler es verwenden möchte.
Es sollte auch alle großen Themen in Swagger erwähnen und auf die verwandten Themen verweisen. Da die Dokumentation für Swagger neu ist, müssen Sie möglicherweise erste Versionen dieser verwandten Themen erstellen.
Einführung - Installation - Setup (Entwicklung in Node.js)
Einführung:
Swagger ist ein Satz von Regeln / Spezifikationen für ein Format, das REST-APIs beschreibt. Es bietet ein leistungsfähiges und aktiv entwickeltes Ökosystem von Tools rund um diese formale Spezifikation wie Codegeneratoren und Editoren. Das Beste an Swagger ist, dass die Dokumentation von Methoden, Parametern und Modellen eng in den Servercode integriert ist, sodass APIs immer synchron bleiben. Hier ist ein Link, der einen kurzen Überblick über das Prahlerische gibt: Erste Schritte.
Schreibvorgaben:
Die Spezifikationen können entweder in JSON oder YAML geschrieben werden. Und so machen wir die Datei swagger.json oder swagger.yaml entsprechend. Der Online-Editor kann zum Erstellen der Datei verwendet werden. Hier ist ein Link, der die Syntax für Spezifikationen beschreibt: http://swagger.io/specification/
Möglichkeiten, Swagger zu verwenden:
- API-first-Ansatz (Top-down-Ansatz): Verwenden Sie den Swagger-Editor → Schreiben Sie Swagger-Definitionen → Verwenden Sie swagger-codegen und swagger-ui, um APIs zu generieren
- Service-First-Ansatz (Bottom-Up-Ansatz): Entwickeln Sie JAX-RS-Ressourcenklassen mithilfe von Swagger-Anmerkungen. → Verwenden Sie Swagger-Core, um die Swagger-Definitionen automatisch zu generieren. Dies kann während des Maven Builds während des Swagger Maven Plugins durchgeführt werden.
Installation und Einrichtung
In diesem Abschnitt werden wir swagger installieren, die swagger-Benutzeroberfläche einrichten und Server-Side- und Client-SDK mit diesem generieren. Um Swagger mit dem Node Package Manager zu installieren, führen Sie den folgenden Befehl aus:
npm install -g swagger
Die Verwendung des '-g'-Flags stellt sicher, dass das Modul global installiert wird. Als Nächstes erstellen wir ein Projekt mit dem folgenden Befehl:
swagger project create <project-name>
Dadurch wird der Benutzer aufgefordert, ein Framework für die Entwicklung der REST-APIs auszuwählen. Express kann für dasselbe ausgewählt werden. Dadurch wird das Projektverzeichnis mit den folgenden Elementen und einer README.md-Datei in jedem von ihnen erstellt:
- api /
- Steuerungen /
- Helfer /
- Spott /
- stolzieren/
- config /
- Prüfung/
- api /
- Steuerungen /
- Helfer
- api /
- app.js
- package.json
Der Server ist jetzt grundsätzlich bereit und kann mit diesem Befehl gestartet werden, um im Projektstamm ausgeführt zu werden:
swagger project start
Wenn der app.js als localhost und die Portnummer in der Datei app.js nicht geändert wird, wird der Server unter folgender app.js gestartet: http://localhost:10010 Nun kann die Swagger-Benutzeroberfläche zur Weiterentwicklung unserer REST-APIs verwendet werden. Dies kann in einem neuen Terminal gestartet werden mit:
swagger project edit
Dadurch wird der Swagger-Editor in einem Browser-Tab an einem zufällig generierten Port geöffnet. In der Datei swagger.yaml ist bereits ein Beispiel für eine hallo GET-Anfrage vorhanden. Jede weitere Änderung dieser Datei führt dazu, dass der Server von selbst neu gestartet wird.
Im Pfadabschnitt sollte der Wert für den x-swagger-router-controller der Javascript-Dateiname im Controller-Ordner sein. Als Beispiel sollte hello_world.js im Controller-Verzeichnis vorhanden sein. Der Wert für den Parameter operationId repräsentiert auch den Funktionsnamen in der obigen Javascript-Datei. Hier sollte Geschäftslogik geschrieben werden. Damit ist unser Swagger-Setup vollständig und kann zur Weiterentwicklung unserer API verwendet werden.