webentwicklung-frage-antwort-db.com.de

Konvertierung der Swagger-Spezifikation JSON in HTML-Dokumentation

Für einige REST - APIs, die in PHP geschrieben wurden, wurde ich gebeten, Swagger -Dokumentation zu erstellen. Da ich keine einfache Möglichkeit wusste, diesen vorhandenen APIs Anmerkungen hinzuzufügen und eine solche Dokumentation zu erstellen, habe ich diesen Editor um einige erst einmal zu generieren.

Ich habe die JSON- und YAML-Dateien gespeichert, die mit diesem Editor erstellt wurden, und jetzt muss ich die endgültige interaktive Swagger-Dokumentation erstellen (diese Anweisung mag sich naiv und vage anhören).

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

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

yamlswaggerswagger-php
55
Salil

Ich war nicht zufrieden mit swagger-codegen, als ich nach einem Werkzeug dafür suchte, also schrieb ich mein eigenes. Werfen Sie einen Blick auf bootprint-swagger

Das Hauptziel im Vergleich zu swagger-codegen besteht darin, ein einfaches Setup bereitzustellen (obwohl Sie nodejs benötigen) ..__ und es sollte einfach sein, Styling und Vorlagen an Ihre eigenen Bedürfnisse anzupassen. Dies ist eine der Hauptfunktionen von bootprint) -Projekt

30
Nils Knappmeier

Check out pretty-Swag

Es hat

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

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

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

16
TLJ

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

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

13
djb

Versuchen Sie, redoc-cli zu verwenden.

Ich habe bootprint-openapi verwendet, um eine Reihe von Dateien (bundle.js, bundle.js.map, index.html, main.css und main.css.map) zu generieren. Anschließend können Sie sie mit html-inline in eine einzige .html-Datei konvertieren Erzeugen Sie eine einfache index.html-Datei. 

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

Installation:

npm install -g redoc-cli

Verwendungszweck:

redoc-cli bundle -o index.html swagger.json
13
VicJordan

Alles war zu schwierig oder schlecht dokumentiert, also löste ich dies mit einem einfachen Skript swagger-yaml-to-html.py , 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 für die Arbeit mit JSON zu ändern.

7
oseiskar

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

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

in

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

der Ordner dist enthält jetzt alles, was Sie brauchen und kann so verteilt werden, wie es ist

6
user1928596

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/[email protected]/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 lediglich path/to/my/swagger.yaml vom selben Standort aus bedienen.
(oder verwenden Sie CORS-Header)

5
Kris Randall

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

  1. Phar-Datei herunterladen https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Installieren Sie Composer https://getcomposer.org/download/
  3. Machen Sie composer.json
  4. Klon Swagger-PHP/Bibliothek
  5. Klon Swagger-Ui/Bibliothek
  6. Erstellen Sie Ressourcen- und Modell-PHP-Klassen für die API 
  7. Führen Sie die Datei PHP 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 index.php im Ordner "swagger-ui dist" an 

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

2
Syed Raza Mehdi

Es gibt ein kleines Java-Programm , das aus einer yaml-Datei Dokumente (adoc oder md) 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 .

0
Erando