Wygeneruj PDF z dokumentacji Swagger API

Użyłem interfejsu użytkownika Swagger do wyświetlenia moich usług sieci Web REST i hostowałem je na serwerze.

Jednak ta usługa Swaggera jest dostępna tylko na określonym serwerze. Jeśli chcę pracować w trybie offline, czy ktoś wie, jak mogę utworzyć statyczny plik PDF za pomocą interfejsu Swagger UI i pracować z nim? Ponadto plik PDF można łatwo udostępnić osobom, które nie mają dostępu do serwera.

Wielkie dzięki!

Poręczny sposób: Korzystanie z drukowania / podglądu w przeglądarce

1. Ukryj okienko edytora
2. Podgląd wydruku (użyłem Firefoxa, inne też dobrze)
3. Zmień ustawienia strony i wydrukuj do formatu PDF

Wymyśliłem sposób, używając https://github.com/springfox/springfox i https://github.com/RobWin/swagger2markup

Użyłem Swaggera 2 do wykonania dokumentacji.

Możesz zmodyfikować swój projekt REST, aby podczas budowania projektu tworzyć potrzebne dokumenty statyczne (html, pdf itp.).

Jeśli masz projekt Java Maven, możesz użyć poniższego fragmentu kodu. Wykorzystuje szereg wtyczek do generowania pliku PDF i dokumentacji html (zasobów REST projektu).

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

Należy pamiętać, że kolejność wykonywania ma znaczenie, ponieważ wyjście jednej wtyczki staje się wejściem do następnej:

<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>

Wtyczka asciidoctor zakłada istnienie pliku adoc do pracy. Możesz utworzyć taki, który po prostu zbiera te, które zostały utworzone przez wtyczkę swagger2markup:

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

Jeśli chcesz, aby wygenerowany dokument html stał się częścią twojego pliku wojennego, musisz upewnić się, że znajduje się on na najwyższym poziomie - pliki statyczne w folderze WEB-INF nie będą obsługiwane. Możesz to zrobić za pomocą wtyczki maven-war:

<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>

Wtyczka war działa na wygenerowanej dokumentacji - w związku z tym musisz upewnić się, że te wtyczki zostały wykonane we wcześniejszej fazie.

Stworzyłem witrynę internetową https://www.swdoc.org/, która konkretnie odnosi się do problemu. Więc automatyzuje swagger.json -> Asciidoc, Asciidoc -> pdftransformację, jak sugerowano w odpowiedziach. Zaletą tego jest to, że nie musisz przechodzić przez procedury instalacji. Akceptuje dokument specyfikacji w postaci adresu URL lub po prostu surowego pliku json. Projekt jest napisany w C #, a jego strona to https://github.com/Irdis/SwDoc

EDYTOWAĆ

Dobrym pomysłem może być sprawdzenie poprawności specyfikacji json tutaj: http://editor.swagger.io/, jeśli masz jakiekolwiek problemy z SwDoc, takie jak niekompletny generowany plik PDF.

Do kasy https://mrin9.github.io/RapiPdf niestandardowy element z dużą ilością funkcji dostosowywania i lokalizacji.

Zastrzeżenie: jestem autorem tego pakietu

Dla mnie najłatwiejszym rozwiązaniem było zaimportowanie swaggera (v2) do Postmana, a następnie przejście do widoku internetowego. Tam możesz wybrać widok „pojedynczej kolumny” i użyć przeglądarki, aby wydrukować do formatu PDF. Nie jest to rozwiązanie zautomatyzowane / zintegrowane, ale dobre do jednorazowego użytku. Obsługuje szerokość papieru znacznie lepiej niż drukowanie z editor2.swagger.io, gdzie paski przewijania powodują ukrywanie części treści.