Générer des PDF à partir de Swagger documentation de l'API

J'ai trouvé un moyen à l'aide de https://github.com/springfox/springfox et
https://github.com/RobWin/swagger2markup

Utilisé Swagger 2 pour mettre en œuvre la documentation.

Vous pouvez modifier votre REPOS, de projet, de manière à produire les documents statiques (html, pdf, etc) lors de la construction du projet.

Si vous avez un Java projet Maven, vous pouvez utiliser le pom extrait de code ci-dessous. Il utilise une série de plugins pour générer un fichier pdf et une documentation au format html (du projet de REPOS ressources).

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

S'il vous plaît être conscient que l'ordre d'exécution des questions, depuis la sortie d'un plugin, devient l'entrée de la suivante:

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

La asciidoctor plugin suppose l'existence d'un .adoc fichier pour travailler sur.
Vous pouvez créer simplement la collecte de celles qui ont été créés par le swagger2markup plugin:

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

Si vous voulez que votre document html généré pour devenir une partie de votre fichier war, vous devez vous assurer qu'il est présent sur le plus haut niveau statique de fichiers dans le dossier WEB-INF ne sera pas servi.
Vous pouvez le faire dans le maven-guerre-plugin:

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

La guerre plugin fonctionne sur la documentation générée, en tant que tel, vous devez vous assurer que ces plugins ont été exécutées dans une phase antérieure.

Pour moi la solution la plus simple était de les importer swagger (v2) en Facteur, puis aller à la vue web. Là, vous pouvez choisir "seule la colonne" afficher et utiliser le navigateur pour imprimer au format pdf. Pas un automatisée/solution intégrée, mais bon pour à usage unique. Il gère papier-largeur beaucoup mieux que l'impression à partir de rédacteur2.swagger.io, où les barres de défilement cause des portions de contenu à être caché.