Konvertieren von Swagger-Spezifikation JSON in HTML-Dokumentation

86

Für einige in PHP geschriebene REST-APIs wurde ich gebeten, eine Swagger- Dokumentation zu erstellen. Da mir keine einfache Möglichkeit bekannt war, diesen vorhandenen APIs Anmerkungen hinzuzufügen und eine solche Dokumentation zu erstellen, habe ich diesen Editor verwendet , um einige zu generieren.

Ich habe die mit diesem Editor erstellten JSON- und YAML-Dateien gespeichert und muss nun die endgültige interaktive Swagger-Dokumentation erstellen (diese Aussage klingt möglicherweise naiv und vage).

Kann mir bitte jemand mitteilen, wie ich die Swagger JSON-Spezifikationsdatei in die tatsächliche Swagger-Dokumentation konvertieren kann?

Ich bin auf der Windows-Plattform und weiß nichts über Ant / Maven.

yaml swagger swagger-php Salil
quelle
Ich habe versucht [ github.com/wordnik/swagger-ui weiblich ( Swagger UI), aber es rendert mein json nicht. Die einzige Warnung lautet "Diese API verwendet eine veraltete Version von Swagger! Weitere Informationen finden Sie unter github.com/wordnik/swagger-core/wiki. "
Salil

Antworten:

41

Ich war nicht zufrieden damit, swagger-codegenals ich nach einem Werkzeug suchte, also schrieb ich mein eigenes. Schauen Sie sich Bootprint-Swagger an

Das Hauptziel im Vergleich zu swagger-codegenist die Bereitstellung einer einfachen Einrichtung (obwohl Sie nodejs benötigen). Und es sollte einfach Styling und Vorlagen an die eigenen Bedürfnisse anzupassen sein, was eine Kernfunktionalität der ist Stiefelabdruck -project

Nils Knappmeier
quelle
8
Warnung: Ab 11/2016 hat der Autor von bootprint-swagger das Projekt offenbar aufgegeben. swagger-codegen wird immer noch gut unterstützt.
Brent Matzelle
21
Ich bin der Autor und der Text sagt: "Es tut mir leid zu sagen, dass ich in naher Zukunft keine neuen Funktionen für dieses Projekt entwickeln kann. Aber: Ich werde wahrscheinlich in der Lage sein, Pull-Anfragen zu diskutieren und zusammenzuführen. und neue Versionen zu veröffentlichen. " Sie könnten das als verlassen bezeichnen, ich würde es "in der Warteschleife" nennen. Ich werde auch alle einladen, die daran interessiert sind, zu dem Projekt beizutragen.
Nils Knappmeier
1
Gefunden, dass spectacleviel besser aussehende Dokumentation von
Prahler
51

Versuchen Sie, redoc-cli zu verwenden .

Ich war mit Stiefelabdruck-OpenAPI von dem ich eine Reihe von Dateien (Erzeugung bundle.js, bundle.js.map, index.html, main.cssund main.css.map) und dann können Sie es in eine einzige konvertieren .htmlDatei mit HTML-Inline eine einfache generieren index.htmlDatei.

Dann fand ich redoc-cli sehr einfach zu bedienen und die Ausgabe ist wirklich großartig, eine einzelne und schöne index.html- Datei.

Installation :

npm install -g redoc-cli

Verwendung :

redoc-cli bundle -o index.html swagger.json
Vikasdeep Singh
quelle
8
Dieses Tool ist wirklich die schönste Ausgabe aller genannten Tools.
Jakub Moravec
Die generierte All-in-One-HTML-Datei ist ziemlich groß. Dies gilt auch für die Abhängigkeit der JS-Bibliothek (~ 800 KB) beim Live-Rendering aus benutzerdefiniertem HTML. Weiß jemand, wie die Größe reduziert werden kann?
Aaronqli
1
Dieser ist bei weitem der beste imo, und da wir ihn für Entwickler erstellen, die Desktops verwenden, ist die Ausgabegröße kein Problem.
Milosmns
3
Die Verwendung eines direkten ausführbaren Namen funktioniert nicht immer, die Ausführung durch npx redoc-cli ...ist zuverlässiger.
Hockendes Kätzchen
2
Sehr schöne Ausgabe. Danke für den Vorschlag.
Sahil Jain
19

Schauen Sie sich Pretty-Swag an

Es hat

  1. Ähnlich wie das rechte Bedienfeld von Swagger-Editor
  2. Suchen / Filtern
  3. Schema Faltung
  4. Live-Feedback
  5. Ausgabe als einzelne HTML-Datei

Ich habe mir Swagger Editor angesehen und dachte, es könnte das Vorschaufenster exportieren, aber es stellte sich heraus, dass dies nicht möglich ist. Also habe ich meine eigene Version davon geschrieben.

Vollständige Offenlegung: Ich bin der Autor des Tools.

TLJ
quelle
1
Ich habe festgestellt, dass Pretty-Swag ein unkompliziertes und ideales Tool mit geeigneten CLI- und API-Einstiegspunkten ist. Meine einzige Beschwerde (und die, die mich gezwungen hat, mich stattdessen mit der Komplexität von swagger-ui zu befassen) war das Versagen, mit der Objektzusammensetzung / -erweiterung richtig umzugehen. Jede Verwendung allOfin dem Dokument führt undefinedselbst in den einfachsten Szenarien zu einem "Zusammenführen" eines einzelnen Objekts, was einer Nichtverwendung entspricht allOf.
HonoredMule
3
Gerade ausgerollte allOfFunktion für Sie. Hör zu.
TLJ
1
Scheint Swagger / OpenAPI V3
SeinopSys
15

Siehe das swagger-api / swagger-codegen- Projekt auf GitHub; Das Projekt README zeigt, wie man damit statisches HTML generiert. Siehe Generieren einer statischen HTML-API-Dokumentation .

Wenn Sie die Datei swagger.json anzeigen möchten, können Sie die Swagger-Benutzeroberfläche installieren und ausführen. Sie stellen es einfach auf einem Webserver bereit (dem dist-Ordner, nachdem Sie das Repo von GitHub geklont haben) und zeigen die Swagger-Benutzeroberfläche in Ihrem Browser an. Es ist eine JavaScript-App.

djb
quelle
Vielen Dank. Mein Problem war, dass die Prahlerei-Benutzeroberfläche keine 2.0-Spezifikation akzeptierte. Dies scheint jedoch die einfachste Antwort zu sein, daher werde ich dies (vorerst) akzeptieren.
Salil
Die Swagger-Tools werden für 2.0 noch weiterentwickelt. Ich habe jedoch festgestellt, dass die Swagger-Benutzeroberfläche für meine 2.0-Dateien funktioniert, die mit "swagger" beginnen: "2.0",
djb
Außerdem können Sie im Swagger-Editor die JSON-Spezifikation (nicht als YAML, sondern als JSON) exportieren, und die Swagger-Benutzeroberfläche sollte dies lesen können. (Hinweis: Die Datei swagger.json muss sich auf demselben Host / Port wie die Swagger-UI-App befinden, oder Sie müssen CORS aktivieren. Siehe README.md im Swagger-Editor auf GitHub
djb
14

Alles war zu schwierig oder schlecht dokumentiert, also habe ich dies mit einem einfachen Skript swagger-yaml-to-html.py gelöst , das so funktioniert

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

Dies ist für YAML, aber es ist auch trivial, es so zu ändern, dass es mit JSON funktioniert.

oseiskar
quelle
13

Ich habe viel Zeit verbracht und viele verschiedene Lösungen ausprobiert - am Ende habe ich es so gemacht:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>

Sie müssen nur den Pfad / to / my / swagger.yaml vom selben Ort aus bedienen lassen .
(oder verwenden Sie CORS-Header)

Kris Randall
quelle
Super, danke! Ich habe <link rel = " stylesheet " href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "> </ script > verwendet
Erando
1
Ich fand, dass dies die beste Lösung ist, ohne dass irgendetwas installiert wird!
KurioZ7
Extrem hilfreich. Sie haben viel Zeit gespart.
Kalpesh Khule
7

Sie können swagger ui auch herunterladen von: https://github.com/swagger-api/swagger-ui , nehmen Sie den dist-Ordner, ändern Sie index.html: ändern Sie den Konstruktor

const ui = SwaggerUIBundle({
    url: ...,

in

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

Jetzt enthält der dist-Ordner alles, was Sie brauchen, und kann unverändert verteilt werden

user1928596
quelle
2

Schauen Sie sich diesen Link an: http://zircote.com/swagger-php/installation.html

  1. Laden Sie die Phar-Datei https://github.com/zircote/swagger-php/blob/master/swagger.phar herunter
  2. Installieren Sie Composer https://getcomposer.org/download/
  3. Machen Sie composer.json
  4. Klonen Sie swagger-php / library
  5. Klonen Sie swagger-ui / library
  6. Erstellen Sie Ressourcen- und Modell-PHP-Klassen für die API
  7. Führen Sie die PHP-Datei aus, um den JSON zu generieren
  8. Geben Sie den Pfad von json in api-doc.json an
  9. Geben Sie den Pfad von api-doc.json in der Datei index.php im Ordner swagger-ui dist an

Wenn Sie weitere Hilfe benötigen, wenden Sie sich bitte an uns.

Syed Raza Mehdi
quelle
1
Gibt es einen Online-Editor (außer Swagger-Editor), der dies für mich generieren kann? Ich möchte meine PHP-APIs nicht mit Anmerkungen versehen, wenn es einen einfacheren Weg gibt. Das Problem, das ich herausgefunden habe, ist, dass der Swagger-Editor die Swagger-Spezifikation v2.0 generiert, und Swagger-UI behandelt dies derzeit nicht.
Salil
@Salil alles was ich weiß ist, dass swagger einen eigenen Online-Editor zur Verfügung stellt, dh editor.swagger.wordnik.com. Mir ist kein anderer Online-Editor bekannt. Wenn Sie einen finden, teilen Sie ihn uns mit, danke :)
Syed Raza Mehdi
1

Es gibt ein kleines Java-Programm, das Dokumente (adoc oder md) aus einer yaml-Datei generiert.

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

Leider unterstützt es nur OpenAPI 2.0 , nicht jedoch OpenAPI 3.0 .

Erando
quelle
1

Für Swagger API 3.0 funktioniert das Generieren von HTML2-Clientcode aus dem Online-Swagger-Editor hervorragend für mich!

Kumar S.
quelle