webentwicklung-frage-antwort-db.com.de

Statische Dokumente mit Swagger generieren

Gibt es eine Methode zum Erstellen einer statischen Dokumentation für swagger 2.0? Vielleicht wie die 'Vorschau' von editor.swagger.io.

Ich muss statische HTML-Dateien erhalten, damit ich sie in einige statische Dokumente einfügen kann.

Bisher habe ich keinen Weg gefunden, dies zu tun. Ich sehe, dass es Swagger-Codegens static-docs Gibt. Dies funktioniert jedoch nur für Swagger <= 1.2.

42
romeovs

Benutze swagger-codegen:

swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>

Wenn Sie die HTML-Vorlage anpassen möchten:

  1. Klonen Sie das Swagger-Codegen-Projekt aus github
  2. Kopieren Sie den modules/swagger-codegen/src/main/resources/htmlDocs2-Ordner an einen anderen Ort, zum Beispiel: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
  3. Passen Sie die .mustache-Vorlagen in ~/templates an Ihre Anforderungen an.
  4. Führen Sie Folgendes aus: swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> für <templates path> sollte im obigen Beispiel ~/templates sein.
19
BananaWanted

Wenn Sie statische Dokumente einfach erstellen möchten, sollten Sie Spectacle betrachten.

npm install spectacle-docs, wenn Sie ein Skript in Ihren package.json einfügen möchten, oder npm install -g spectacle-docs, wenn es überall verfügbar sein soll.

Dann können Sie einfach spectacle spec.yaml ausführen, mit Optionen zum Erstellen eines bestimmten Verzeichnisses, Ausführen eines Servers und/oder Beobachten der Spezifikationsdatei und Aktualisieren nach Bedarf.

13
Will

Die statischen Dokumente in 2.0 sind für 2.0 implementiert. Sehen Sie hier die ./bin/static-docs.sh:

https://github.com/swagger-api/swagger-codegen/tree/master/bin

5
fehguy

Wenn Sie speziell nach Swagger 2.0 suchen, möchte ich Sie auf meine Antwort in Konvertieren der JSON-Spezifikation von Swagger in HTML-Dokumentation Hinweisen, obwohl ich glaube, dass Swagger-Codegen jetzt Swagger 2.0 unterstützt .

2
Nils Knappmeier

Sie können verwenden:

1
slal

"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 (beispielsweise ohne die Schaltfläche "Jetzt testen") ausführt, ist für 2.0 noch nicht implementiert, sollte jedoch in den kommenden Wochen verfügbar sein. 

1
Ron

Klicken Sie auf die Vorschau-Dokumente, verwenden Sie das Chrome-Addon "Seite speichern" (rechter Mausklick auf Seite -> "Seite speichern"). Das Ergebnis ist eine einzige HTML-Datei.

0
Jiro Matchonson

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 erstellen, und das Ergebnis ist gut lesbar. Es scheint sehr konfigurierbar und erweiterbar zu sein, obwohl ich es noch nicht probiert habe.

0
paul

Normalerweise mache ich das mit https://editor.swagger.io/ . Keine Installation oder irgendetwas erforderlich.

Kopieren Sie Ihre yml-Datei in den Editor und wählen Sie "Client generieren> html2", um statische HTML-Dateien in einer Zip-Datei zu generieren.

0
Semaphor

Haben Sie Ihre OpenAPI/Swagger-Spezifikation in spec.json (kann auch in YAML sein) mit Spectacles Docker-Image statischer Build kann wie folgt generiert werden:

mkdir -m 777 build && docker run --rm \
    -v `pwd`/build:/tmp/build \
    -v `pwd`/spec.json:/tmp/spec.json \
    sourcey/spectacle \
    spectacle -t /tmp/build /tmp/spec.json
0
saaj