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

91

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!

pdf  swagger-ui 
— Aman Mohammed
source

Réponses:

39

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

entrez la description de l'image ici

— Osify
source
Facile! La documentation sort plutôt bien.
— ShaTin
1
Vous pouvez même choisir entre deux conceptions de documentation tant qu'il y a deux services Swagger: editor.swagger.io (nouveau) et editor2.swagger.io (précédent)!
— naXa
L'interface utilisateur HTML bcos swagger efficace mais avec perte a plusieurs onglets.Pour les paramètres d'une méthode POST / PUT, vous devez choisir entre l'onglet modèle et l'onglet de valeur d'exemple, puis dans la version imprimée au format PDF l'un d'entre eux est à jamais caché :(
— chrisinmtown
Cela n'a pas fonctionné pour moi. Chaque point de terminaison serait coupé avec la fin de la page (quelle que soit la configuration de page que j'ai utilisée). La page suivante commencerait alors en haut du bloc Endpoint suivant. Peut-être que quelque chose a changé depuis que cette réponse a été écrite.
— killa-byte le
Je vois toujours que c'est réalisable, vous devrez peut-être adapter la marge. Essayez de editor.swagger.io
— Osify le
33

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.

— Aman Mohammed
source
Salut, j'essaie également de générer de la documentation hors ligne à l'aide de swagger. Êtes-vous capable de générer de la documentation swagger ??
— Sunil Rk
oui, j'ai utilisé les exemples de projets et y ai intégré mon code de service Web et j'ai pu générer la documentation.
— Aman Mohammed
1
Pouvez-vous me dire en bref, comment je peux intégrer mon service Web aux exemples que vous avez mentionnés ci-dessus.
— Sunil Rk
Le projet swagger2markup nécessite une entrée JSON de l'API REST. Si vous téléchargez ce projet gradle et modifiez le fichier swagger.json avec les détails de votre API, puis exécutez la méthode Swagger2MarkupConverterTest JUnit: testSwagger2HtmlConversion, il doit générer le HTML pour vous dans le dossier build / docs / generated / asciidocAsString du projet. Donc en d'autres termes, il y a 2 choses. 1) Générez d'abord le format JSON de votre API REST à l'aide de Swagger Editor. 2) En utilisant ce format JSON, vous pouvez utiliser le projet swagger2markup pour produire une documentation HTML autonome de l'API
— Aman Mohammed
21

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.

— Hervian
source
Salut @Hervian. Très bonne réponse. Je pourrais utiliser votre réponse jusqu'à présent. J'ai deux classes avec le même nom mais dans des packages différents. Cependant, swagger.json contient la définition d'un seul d'entre eux. L'autre est manquant
— edmond
@Hervian J'ai eu des erreurs jusqu'à ce que je fasse ce qui suit 1) créé le fichier src / main / asciidoc / swagger.adoc avec le contenu d'en haut. 2) a ajouté ces propriétés au POM: <phase.generate-documentation> process-classes </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated. asciidoc.directory> Puis lancez "mvn install" et je ne vois aucune erreur mvn ou plugin mais seul le fichier overview.adoc a du contenu; les fichiers définitions.adoc et paths.adoc restent vides. Pls conseiller.
— chrisinmtown
13

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.

— Irdis
source
3
thx, ouais c'est plutôt sympa, je l'utilise pour mes projets de travail. Je pense écrire du code pour prendre en charge openapi 3.0 sur mon temps libre.
— Irdis
2
Toute la gloire aux auteurs des outils sur lesquels il s'appuie, ofc
— Irdis
@Irdis J'ai essayé d'utiliser le lien. Il permet d'analyser le document Swagger 2.0, mais le document que je fournis est Open API 3.0 et il est incapable de générer le document.
— hellowahab
J'ai essayé swagger 3+ - fonctionne bien, il montre du html brut pour les remarques cependant ...
— Sasha Bond
C'est un excellent outil! Si jamais vous rencontrez des problèmes comme moi (comme un pdf généré incomplet), collez votre json ici: editor.swagger.io pour qu'il soit automatiquement validé, corrigez les problèmes et vous serez prêt à revenir à l'outil swdoc et à le générer correctement cette fois.
— Thales Valias le
7

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

— Mrinmoy
source
2
juste testé mais je n'obtiens pas de réponse après avoir cliqué sur "Générer PDF" avec les spécifications de test (petstore)?
— imehl le
1
@imehl Cela fonctionne bien lorsque je me suis testé sur mac / chrome, mac / firefox, mac / safari et windows / chrome. Cela ne fonctionne que sur un navigateur Web qui prend en charge les composants Web tels que Chrome, Firefox et Safari. Si des problèmes persistent, veuillez les connecter sur Github github.com/mrin9/RapiPdf
— Mrinmoy
@Mrinmoy J'ai eu le même problème que imehl, il a ouvert un nouvel onglet mais il s'est fermé immédiatement (ubuntu 18.04 + firefox / chrome à la fois le même résultat). Ensuite, je l'ai fait sur les fenêtres et cela a fonctionné comme un charme. Merci pour cet outil, c'est génial.
— Dabux
3
@Dabux n'a jamais testé sur ubuntu, mais il y a une situation que je connais où les gens sont confrontés au même problème que vous l'avez expliqué, et c'est lorsque vous avez un bloqueur actif en tant que bloqueur ou bloqueur de popup sur le navigateur
— Mrinmoy
@Mrinmoy vous avez raison, j'avais un bloqueur de publicités, c'était à cause de ça, pas à cause du système d'exploitation.
— Dabux
1

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.

— Simon
source
1
essayé d'utiliser cela, mais l'impression via la page Web ajoute également plusieurs liens et d'autres informations.
— hellowahab
Oui, j'aurais dû le mentionner. Ce n'était pas un problème pour mon utilisation.
— Simon
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.