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

J'ai utilisé l'interface utilisateur de Swagger pour afficher mes services Web REST et je les ai hébergés sur un serveur.

Cependant, ce service de Swagger n'est accessible que sur un serveur particulier. Si je souhaite travailler hors ligne, est-ce que quelqu'un sait comment créer un PDF statique à l'aide de l'interface utilisateur de Swagger et l'utiliser? De plus, un PDF est facile à partager avec des personnes qui n'ont pas accès au serveur.

Merci beaucoup!

Manière pratique: utilisation de l'impression / aperçu du navigateur

1. Masquer le volet de l'éditeur
2. Aperçu avant impression (j'ai utilisé Firefox, d'autres très bien)
3. Changer sa mise en page et imprimer en pdf

J'ai trouvé un moyen en utilisant https://github.com/springfox/springfox et https://github.com/RobWin/swagger2markup

Utilisation de Swagger 2 pour implémenter la documentation.

Vous pouvez modifier votre projet REST, afin de produire les documents statiques nécessaires (html, pdf, etc.) lors de la construction du projet.

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

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

Veuillez noter que l'ordre d'exécution est important, puisque la sortie d'un plugin devient l'entrée du suivant:

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

Le plugin asciidoctor suppose l'existence d'un fichier .adoc sur lequel travailler. Vous pouvez en créer un qui rassemble simplement ceux qui ont été créés par le plugin swagger2markup:

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

Si vous voulez que votre document html généré fasse partie de votre fichier war, vous devez vous assurer qu'il est présent au niveau supérieur - les fichiers statiques du dossier WEB-INF ne seront pas servis. Vous pouvez le faire dans le maven-war-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>

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

J'ai créé un site Web https://www.swdoc.org/ qui traite spécifiquement du problème. Donc, il automatise la swagger.json -> Asciidoc, Asciidoc -> pdftransformation comme suggéré dans les réponses. L'avantage de ceci est que vous n'avez pas besoin de suivre les procédures d'installation. Il accepte un document de spécification sous forme d'url ou simplement un json brut. Le projet est écrit en C # et sa page est https://github.com/Irdis/SwDoc

ÉDITER

Ce pourrait être une bonne idée de valider vos spécifications json ici: http://editor.swagger.io/ si vous rencontrez des problèmes avec SwDoc, comme le pdf généré incomplet.

Checkout https://mrin9.github.io/RapiPdf un élément personnalisé avec beaucoup de fonctionnalités de personnalisation et de localisation.

Avertissement: je suis l'auteur de ce package

Pour moi, la solution la plus simple était d'importer swagger (v2) dans Postman, puis d'accéder à la vue Web. Là, vous pouvez choisir la vue "colonne unique" et utiliser le navigateur pour imprimer au format PDF. Pas une solution automatisée / intégrée mais bonne pour un usage unique. Il gère beaucoup mieux la largeur du papier que l'impression à partir de editor2.swagger.io, où les barres de défilement provoquent le masquage de certaines parties du contenu.