it-swarm.com.de

Generieren PDF aus der Swagger-API-Dokumentation

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

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 statische PDF erstellen und damit arbeiten kann? Darüber hinaus ist ein PDF für Benutzer, die keinen Zugriff auf den Server haben, leicht zugänglich.

Danke vielmals!

64
Aman Mohammed

Ich habe einen Weg gefunden, mit https://github.com/springfox/springfox und https://github.com/RobWin/swagger2markup

Verwendete Swagger 2 zum Implementieren der Dokumentation.

29
Aman Mohammed

Praktische Vorgehensweise: Verwenden des Browserdrucks/Vorschau

  1. Editorbereich ausblenden
  2. Druckansicht (ich habe Firefox verwendet, andere auch gut)
  3. Ändern Sie die Seiteneinrichtung und drucken Sie sie als PDF

 enter image description here

26
Osify

Sie können Ihr REST - Projekt ändern, um die erforderlichen statischen Dokumente (HTML, PDF usw.) beim Erstellen des Projekts zu erstellen.

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

  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 geht davon aus, dass eine .adoc-Datei vorhanden ist. 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 Kriegsdatei 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 Kriegs-Plugin arbeitet mit der generierten Dokumentation. Daher müssen Sie sicherstellen, dass diese Plugins in einer früheren Phase ausgeführt wurden.

17
Hervian

Während die Lösung von Amaan Mohammed so aussieht, als würde sie funktionieren, gibt es einen einfacheren Weg, dies zu tun. Werfen Sie einen Blick auf swagger2markup-cli

5
vishal

Ich habe eine Website erstellt https://www.swdoc.org/ , die speziell auf das Problem eingeht. So automatisiert es die swagger.json -> Asciidoc, Asciidoc -> pdf -Transformation, wie in den Antworten vorgeschlagen. Dies hat den Vorteil, dass Sie die Installationsprozeduren nicht durchlaufen müssen. Es akzeptiert ein Spezifikationsdokument in Form einer URL oder nur eines rohen Json. Die Projektseite ist https://github.com/Irdis/SwDoc

0
Irdis

Für mich war es am einfachsten, Swagger (v2) in Postman zu importieren und dann zur Webansicht zu wechseln. Dort können Sie die Ansicht "einspaltig" auswählen und den Browser zum Drucken in PDF verwenden. Keine automatisierte/integrierte Lösung, aber für den einmaligen Gebrauch geeignet. Es verarbeitet Papierbreiten viel besser als das Drucken aus editor2.swagger.io, wo Bildlaufleisten dazu führen, dass Teile des Inhalts ausgeblendet werden. 

0
Simon