Generieren Sie PDF aus der Swagger API-Dokumentation

91

Ich habe die Swagger-Benutzeroberfläche verwendet, um meine REST-Webservices anzuzeigen, und sie auf einem Server gehostet.

Auf diesen Dienst von Swagger kann jedoch nur auf einem bestimmten Server zugegriffen werden. Wenn ich offline arbeiten möchte, weiß jemand, wie ich mit der Swagger-Benutzeroberfläche ein statisches PDF erstellen und damit arbeiten kann? Darüber hinaus kann eine PDF-Datei problemlos an Personen weitergegeben werden, die keinen Zugriff auf den Server haben.

Danke vielmals!

Aman Mohammed
quelle

Antworten:

39

Praktische Methode: Verwenden des Browserdrucks / der Vorschau

  1. Editorfenster ausblenden
  2. Druckvorschau (Ich habe Firefox verwendet, andere auch in Ordnung)
  3. Ändern Sie das Seiten-Setup und drucken Sie es als PDF

Geben Sie hier die Bildbeschreibung ein

Osify
quelle
Einfach! Die Dokumentation kommt ganz gut heraus.
ShaTin
1
Sie können sogar zwischen zwei Dokumentationsdesigns wählen, solange es zwei Swagger-Dienste gibt: editor.swagger.io (neu) und editor2.swagger.io (vorher)!
NaXa
Effektive, aber verlustbehaftete HTML-Benutzeroberfläche von bcos swagger verfügt über mehrere Registerkarten. Für die Parameter einer POST / PUT-Methode müssen Sie zwischen der Registerkarte Modell und der Registerkarte Beispielwert wählen. In der PDF-Version ist eine davon für immer verborgen :(
chrisinmtown
Das hat bei mir nicht funktioniert. Jeder Endpunkt wird mit dem Ende der Seite abgeschnitten (unabhängig davon, welches Seiten-Setup ich verwendet habe). Die nächste Seite beginnt dann oben im nächsten Endpunktblock. Vielleicht hat sich etwas geändert, seit diese Antwort geschrieben wurde.
Killa-Byte
Ich sehe immer noch, dass es funktioniert. Möglicherweise müssen Sie den Rand anpassen. Versuchen Sie es unter editor.swagger.io
Osify
33

Ich habe mithilfe von https://github.com/springfox/springfox und https://github.com/RobWin/swagger2markup einen Weg gefunden

Verwendete Swagger 2, um die Dokumentation zu implementieren.

Aman Mohammed
quelle
Hallo, ich versuche auch, Offline-Dokumentation mit Swagger zu generieren. Können Sie Swagger-Dokumentation generieren?
Sunil Rk
Ja, ich habe die Beispielprojekte verwendet und meinen Webservice-Code in sie integriert und konnte die Dokumentation generieren.
Aman Mohammed
1
Können Sie mir bitte kurz sagen, wie ich meinen Webdienst in die oben genannten Beispiele integrieren kann?
Sunil Rk
Das swagger2markup-Projekt benötigt eine JSON-Eingabe der REST-API. Wenn Sie dieses Gradle-Projekt herunterladen und die Datei swagger.json darin mit Ihren API-Details ändern und dann die Swagger2MarkupConverterTest JUnit-Methode: testSwagger2HtmlConversion ausführen, sollte der HTML-Code für Sie im Ordner build / docs / generate / asciidocAsString des Projekts generiert werden. Mit anderen Worten, es gibt zwei Dinge. 1) Generieren Sie zuerst das JSON-Format für Ihre REST-API mit dem Swagger-Editor. 2) Mit diesem JSON-Format können Sie das Projekt swagger2markup verwenden, um eine eigenständige HTML-Dokumentation der API zu erstellen
Aman Mohammed
21

Sie können Ihr REST-Projekt so ändern, dass beim Erstellen des Projekts die erforderlichen statischen Dokumente (HTML, PDF usw.) erstellt werden.

Wenn Sie ein Java Maven-Projekt haben, können Sie das folgende Pom-Snippet verwenden. Es verwendet eine Reihe von Plugins, um eine PDF- und eine HTML-Dokumentation (der REST-Ressourcen des Projekts) zu generieren.

  1. rest-api -> swagger.json: swagger-maven-plugin
  2. swagger.json -> Asciidoc: swagger2markup-maven-plugin
  3. Asciidoc -> PDF: Asciidoctor-Maven-Plugin

Bitte beachten Sie, dass die Reihenfolge der Ausführung wichtig ist, da die Ausgabe eines Plugins zur Eingabe für das nächste wird:

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>some.package</locations>
                <basePath>/api</basePath>
                <info>
                    <title>Put your REST service's name here</title>
                    <description>Add some description</description>
                    <version>v1</version>
                </info>
                <swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
                <attachSwaggerArtifact>true</attachSwaggerArtifact>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>${phase.generate-documentation}</phase>
            <!-- fx process-classes phase -->
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>io.github.robwin</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>0.9.3</version>
    <configuration>
        <inputDirectory>${project.build.directory}/api</inputDirectory>
        <outputDirectory>${generated.asciidoc.directory}</outputDirectory>
        <!-- specify location to place asciidoc files -->
        <markupLanguage>asciidoc</markupLanguage>
    </configuration>
    <executions>
        <execution>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
        </execution>
    </executions>
</plugin>
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.11</version>
        </dependency>
        <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>1.7.21</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
        <!-- You will need to create an .adoc file. This is the input to this plugin -->
        <sourceDocumentName>swagger.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>2</toclevels>
            <generated>${generated.asciidoc.directory}</generated>
            <!-- this path is referenced in swagger.adoc file. The given file will simply 
                point to the previously create adoc files/assemble them. -->
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <outputDirectory>${generated.html.directory}</outputDirectory>
                <!-- specify location to place html file -->
            </configuration>
        </execution>
        <execution>
            <id>asciidoc-to-pdf</id>
            <phase>${phase.generate-documentation}</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${generated.pdf.directory}</outputDirectory>
                <!-- specify location to place pdf file -->
            </configuration>
        </execution>
    </executions>
</plugin>

Das Asciidoctor-Plugin setzt voraus, dass eine ADOC-Datei vorhanden ist, an der gearbeitet werden kann. Sie können eine erstellen, die einfach diejenigen sammelt, die vom swagger2markup-Plugin erstellt wurden:

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

Wenn Sie möchten, dass Ihr generiertes HTML-Dokument Teil Ihrer War-Datei wird, müssen Sie sicherstellen, dass es auf der obersten Ebene vorhanden ist. Statische Dateien im Ordner WEB-INF werden nicht bereitgestellt. Sie können dies im Maven-War-Plugin tun:

<plugin>
    <artifactId>maven-war-plugin</artifactId>
    <configuration>
        <warSourceDirectory>WebContent</warSourceDirectory>
        <failOnMissingWebXml>false</failOnMissingWebXml>
        <webResources>
            <resource>
                <directory>${generated.html.directory}</directory>
            <!-- Add swagger.pdf to WAR file, so as to make it available as static content. -->
            </resource>
            <resource>
                <directory>${generated.pdf.directory}</directory>
            <!-- Add swagger.html to WAR file, so as to make it available as static content. -->
            </resource>
        </webResources>
    </configuration>
</plugin>

Das War-Plugin arbeitet mit der generierten Dokumentation. Daher müssen Sie sicherstellen, dass diese Plugins in einer früheren Phase ausgeführt wurden.

Hervian
quelle
Hallo @Hervian. Gute Antwort. Ich könnte deine Antwort bisher gebrauchen. Ich habe zwei Klassen mit dem gleichen Namen, aber in verschiedenen Paketen. Die Datei swagger.json enthält jedoch nur die Definition für einen von ihnen. Der andere fehlt
Edmond
@Hervian Ich habe Fehler erhalten, bis ich Folgendes getan habe: 1) Datei src / main / asciidoc / swagger.adoc mit Inhalten von oben erstellt. 2) Diese Eigenschaften wurden dem POM hinzugefügt: <phase.generate-documentation> Prozessklassen </phase.generate-documentation> <generate.asciidoc.directory> $ {project.build.directory} / api-gen </ generate. asciidoc.directory> Führen Sie dann "mvn install" aus und ich sehe keine mvn- oder Plugin-Fehler, sondern nur die Datei summary.adoc enthält Inhalt. Die Dateien definition.adoc und paths.adoc bleiben leer. Bitte empfehlen.
Chrisinmtown
11

Ich habe eine Website https://www.swdoc.org/ erstellt , die sich speziell mit dem Problem befasst. So automatisiert es die swagger.json -> Asciidoc, Asciidoc -> pdfTransformation, wie in den Antworten vorgeschlagen. Dies hat den Vorteil, dass Sie die Installationsverfahren nicht durchlaufen müssen. Es akzeptiert ein Spezifikationsdokument in Form einer URL oder nur eines rohen JSON. Das Projekt ist in C # geschrieben und die Seite lautet https://github.com/Irdis/SwDoc

BEARBEITEN

Es ist möglicherweise eine gute Idee, Ihre JSON-Spezifikationen hier zu überprüfen : http://editor.swagger.io/, wenn Sie Probleme mit SwDoc haben, z. B. wenn das PDF unvollständig generiert wird.

Irdis
quelle
3
Danke, ja, es ist ziemlich schön, ich benutze es für meine Arbeitsprojekte. Ich denke darüber nach, Code zu schreiben, um openapi 3.0 in meiner Freizeit zu unterstützen.
Irdis
2
Alle Ehre den Autoren der Werkzeuge, auf die es sich stützt, ofc
Irdis
@Irdis Ich habe versucht, den Link zu verwenden. Es ermöglicht das Parsen von Swagger 2.0-Dokumenten, aber das von mir bereitgestellte Dokument ist Open API 3.0 und kann das Dokument nicht generieren.
Hellowahab
Ich habe Swagger 3+ ausprobiert - funktioniert gut, es zeigt jedoch rohes HTML für Bemerkungen ...
Sasha Bond
Dies ist ein großartiges Werkzeug! Wenn Sie jemals Probleme haben, wie ich sie hatte (z. B. wenn das PDF unvollständig generiert wird), fügen Sie Ihren json hier ein: editor.swagger.io , um automatisch überprüft zu werden, beheben Sie die Probleme, und Sie können zum swdoc-Tool zurückkehren und es ordnungsgemäß generieren diesmal.
Thales Valias
7

Kasse https://mrin9.github.io/RapiPdf ein benutzerdefiniertes Element mit zahlreichen Anpassungs- und Lokalisierungsfunktionen.

Haftungsausschluss: Ich bin der Autor dieses Pakets

Mrinmoy
quelle
2
gerade getestet, aber ich bekomme keine Antwort, nachdem ich mit der Testspezifikation (Petstore) auf "PDF generieren" geklickt habe?
Imehl
1
@imehl Es funktioniert gut, wenn ich mich auf Mac / Chrome, Mac / Firefox, Mac / Safari und Windows / Chrome getestet habe. Dies funktioniert nur in Webbrowsern, die Webkomponenten wie Chrome, Firefox und Safari unterstützen. Wenn immer noch Probleme auftreten, melden Sie diese bitte in Github an. Github.com/mrin9/RapiPdf
Mrinmoy
@Mrinmoy Ich hatte das gleiche Problem wie imehl, es öffnete neue Registerkarte, aber es schloss sofort (Ubuntu 18.04 + Firefox / Chrome beide das gleiche Ergebnis). Dann habe ich es an Fenstern gemacht und es hat wie ein Zauber funktioniert. Vielen Dank für dieses Tool, es ist fantastisch.
Dabux
3
@Dabux wurde nie auf Ubuntu getestet, aber es gibt eine Situation, von der ich weiß, dass Menschen mit dem gleichen Problem konfrontiert sind, das Sie erklärt haben, und zwar, wenn Sie einen aktiven
As
@Mrinmoy du hast recht, ich hatte einen Werbeblocker an, es war deswegen, nicht wegen des Betriebssystems.
Dabux
1

Für mich war die einfachste Lösung, swagger (v2) in Postman zu importieren und dann zur Webansicht zu wechseln. Dort können Sie die Ansicht "einspaltig" auswählen und mit dem Browser als PDF drucken. Keine automatisierte / integrierte Lösung, aber gut für den einmaligen Gebrauch. Die Papierbreite wird viel besser verarbeitet als beim Drucken in editor2.swagger.io, wo Bildlaufleisten dazu führen, dass Teile des Inhalts ausgeblendet werden.

Simon
quelle
1
Ich habe versucht, dies zu verwenden, aber der Druck über die Webseite fügt auch mehrere Links und andere Informationen hinzu.
Hellowahab
Ja, das hätte ich erwähnen sollen. War für mich kein Problem.
Simon