web-dev-qa-db-fra.com

Produire PDF depuis la documentation de l'API Swagger

J'ai utilisé l'interface utilisateur Swagger pour afficher mes services Web REST et l'héberger sur un serveur.

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

Merci beaucoup!

pdfswagger-ui
64
Aman Mohammed

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

Swagger 2 utilisé pour implémenter la documentation.

29
Aman Mohammed

Manière pratique: Utilisation de l’impression/aperçu dans le navigateur

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

 enter image description here

26
Osify

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 pom ci-dessous. Il utilise une série de plugins pour générer un fichier pdf et une documentation html (des ressources REST du projet).

  1. reste-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, car 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 souhaitez que votre document HTML généré fasse partie de votre fichier war, vous devez vous assurer qu'il est présent au premier niveau - les fichiers statiques du dossier WEB-INF ne seront pas servis. Vous pouvez le faire dans le plugin 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>

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

17
Hervian

Bien que la solution d'Amaan Mohammed semble fonctionner, il existe un moyen plus simple de le faire. Jetez un coup d'œil à swagger2markup-cli . 

5
vishal

J'ai créé un site Web https://www.swdoc.org/ qui traite spécifiquement du problème. Ainsi, il automatise la transformation swagger.json -> Asciidoc, Asciidoc -> pdf comme suggéré dans les réponses. L'avantage de ceci est que vous n'avez pas besoin de passer par les procédures d'installation. Il accepte un document de spécification sous forme d'URL ou simplement un json brut. La page du projet est https://github.com/Irdis/SwDoc

0
Irdis

Pour moi, la solution la plus simple consistait à importer swagger (v2) dans Postman, puis à accéder à la vue Web. Là, vous pouvez choisir la vue "colonne unique" et utiliser le navigateur pour imprimer en pdf. Pas une solution automatisée/intégrée mais bonne pour un usage unique. La largeur du papier est beaucoup mieux gérée que l’impression à partir de editor2.swagger.io, où les barres de défilement masquent des parties du contenu. 

0
Simon