Gibt es eine Methode zum Erstellen einer statischen Dokumentation für Swagger 2.0? Vielleicht wie die 'Vorschau' auf editor.swagger.io.
Ich benötige statische HTML-Dateien, damit ich sie in einige statische Dokumente aufnehmen kann.
Bisher habe ich keinen Weg gefunden, dies zu tun. Ich sehe, dass es swagger-codegens static-docs gibt, aber dies funktioniert nur für swagger <= 1.2.
Antworten:
swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>
modules/swagger-codegen/src/main/resources/htmlDocs2Ordner an einen anderen Ort, zum Beispiel:cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates.mustacheVorlagen ~/templatesan Ihre Anforderungen an.swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path>for <templates path>sollte ~/templatesim obigen Beispiel sein.Wenn Sie nur auf einfache Weise statische Dokumente erstellen möchten, ziehen Sie Spectacle in Betracht .
npm install spectacle-docswenn Sie ein Skript in Ihr Skript einfügen möchten package.jsonoder npm install -g spectacle-docswenn es überall verfügbar sein soll.
Dann können Sie einfach spectacle spec.yamlmit Optionen zum Erstellen in einem bestimmten Verzeichnis ausführen, einen Server ausführen und / oder die Spezifikationsdatei ansehen und nach Bedarf aktualisieren.
spec.yamlbezieht sich auf die Swagger-Spezifikation selbst, die entweder in JSON- oder YAML-Syntax ausgedrückt werden kann.
Die statischen Dokumente in 2.0 sind für 2.0 implementiert. siehe die ./bin/static-docs.sh hier:
https://github.com/swagger-api/swagger-codegen/tree/master/bin
Sie können verwenden:
Sie können den swagger-codegenBefehl wie bereits erwähnt verwenden, aber die Ausgabe, die Sie erhalten -l htmloder -l html2die nicht interaktiv ist, ist wie die Swagger-Benutzeroberfläche.
Gehen Sie folgendermaßen vor, um eine interaktive statische Seite wie die Swagger-Benutzeroberfläche zu erhalten:
url: "http://localhost:8000/swagger.ymlUm dies zu testen, können Sie mit python3 einen einfachen HTTP-Server ausführen.
python3 -m http.server 8000 --directory public
Öffnen Sie http: // localhost: 8000 / und probieren Sie es aus!
Wenn Sie speziell nach Swagger 2.0 suchen, möchte ich Sie auf meine Antwort in Konvertieren der Swagger-Spezifikation JSON in HTML-Dokumentation verweisen, obwohl ich glaube, dass Swagger-Codegen Swagger 2.0 inzwischen unterstützt.
Normalerweise mache ich das mit https://editor.swagger.io/ . Keine Installation oder irgendetwas erforderlich.
Kopieren Sie Ihre XML-Datei in den Editor und wählen Sie "Client generieren> HTML2". Dadurch werden statische HTML-Dateien in einer Zip-Datei generiert.
"statische" Dokumente können verschiedene Bedeutungen haben.
Wenn Sie nach einer interaktiven Anzeige suchen (wie die Vorschau des Editors), haben Sie swagger-ui ( https://github.com/swagger-api/swagger-ui ).
Der Code im Codegen, der die statischeren Dokumente ausführt (z. B. ohne die Schaltfläche "Jetzt testen"), ist für 2.0 noch nicht implementiert, sollte jedoch in den kommenden Wochen verfügbar sein.
Ich habe das hier beschriebene Verfahren verwendet http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven .
Es verwendet Maven, um statische Dokumentation zu generieren, und das Ergebnis ist gut lesbar. Es scheint sehr konfigurierbar und erweiterbar zu sein, obwohl ich es noch nicht ausprobiert habe.
Klicken Sie auf Vorschau-Dokumente, verwenden Sie das Chrome-Addon 'Save Page WE' (Rechtsklick auf Seite -> 'Save Page We'). Das Ergebnis ist eine einzelne HTML-Datei (sie kann nicht angeklickt werden, sodass Sie auf alles klicken müssen, was Sie sehen möchten).
Zum Rendern einer OpenAPI 3-Spezifikation in eine eigenständige HTML-Datei kann redoc-cli verwendet werden. Sie können die PetAPore OpenAPI 3-Spezifikation von ReDoc als Beispiel verwenden.
mkdir -p -m 777 build && docker run --rm --user 1000 \
-v $PWD/build:/tmp/build -w /tmp/build \
-v $PWD/openapi.yaml:/tmp/openapi.yaml node:14-slim npx -q \
redoc-cli bundle /tmp/openapi.yaml
Dies wird build/redoc-static.htmlin Ihrem aktuellen Verzeichnis generiert .
Um zu vermeiden, dass Sie auf die Installation warten, können Sie sich auch ein Docker-Image redoc-clientsprechend erstellen Dockerfileoder redoc-cliauf Ihrem Betriebssystem installieren , wenn Sie NodeJS dort haben npm install -g redoc-cli.
ReDoc hat auch einen Kompatibilitätsmodus für OpenAPI 2 / Swagger, daher funktioniert das oben Genannte auch für Gesagte Petstore OpenAPI 2-Spezifikation funktioniert .
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0
Alternativ gibt es das OpenAPI 2-only Spectacle und sein offizielles Docker-Image . Es kann ähnlich verwendet werden wie:
mkdir -p -m 777 build && docker run --rm --user 1000 \
-v $PWD/build:/tmp/build \
-v $PWD/swagger.yaml:/tmp/swagger.yaml sourcey/spectacle \
spectacle -t /tmp/build /tmp/swagger.yaml
Es generiert einen statischen Build, der fast in sich geschlossen ist (außer das Laden von jQuery, von code.jquery.comdem aus irgendeinem Grund mein Ende aus langsam war).
├── index.html
├── javascripts
│ ├── spectacle.js
│ └── spectacle.min.js
└── stylesheets
├── foundation.css
├── foundation.min.css
├── spectacle.css
└── spectacle.min.css
Nehmen Sie die Abhängigkeit für Prahlerei in Ihren Pom auf.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
Und versuchen Sie es mit -> https://editor.swagger.io/