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.

Verwenden Sie 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 von Github
2. Kopieren Sie den modules/swagger-codegen/src/main/resources/htmlDocs2Ordner an einen anderen Ort, zum Beispiel:cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
3. Passen Sie die .mustacheVorlagen ~/templatesan Ihre Anforderungen an.
4. Run: 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.

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:

• swagger-ui : Klonen Sie einfach das Projekt und kopieren Sie Ihren JSON in das Basisverzeichnis
• Prahler-Codegen

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:

Installieren

• Gehen Sie zu https://github.com/swagger-api/swagger-ui/releases und laden Sie die neueste Version als ZIP-Datei herunter.
• Entpacken Sie die Datei und kopieren Sie alles im Ordner ./dist in das Verzeichnis, das der Webserver bereitstellen soll. Zum Beispiel Gitlab Seiten brauchen es in den sein muss ./public Ordner im Repository.
• Kopieren Sie Ihre Datei swagger.yml in den Ordner ./public .
• Öffnen Sie die Datei ./public/index.html und aktualisieren Sie die URL so, dass sich die Swagger-Datei auf dem Webserver befindet. Für einen lokalen Server kann dies sein:url: "http://localhost:8000/swagger.yml

Prüfung

Um 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).

OpenAPI 3

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.

OpenAPI 2

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/