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

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

Cependant, ce service de Swagger est uniquement accessible sur un serveur particulier. Si je veux travailler hors ligne, est-ce que quelqu’un sait comment créer un fichier PDF statique à l’aide de l’interface utilisateur Swagger et l’utiliser? De plus, un fichier PDF est facile à partager avec des personnes n’ayant pas access au serveur.

Merci beaucoup!

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

    Utilisé Swagger 2 pour implémenter la documentation.

    Manière pratique: Utiliser l’impression / prévisualisation du navigateur

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

    entrer la description de l'image ici

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

    Sachez que l’ordre d’exécution est important, car la sortie d’un plugin devient l’entrée du suivant:

     com.github.kongchen swagger-maven-plugin 3.1.3    false some.package /api  Put your REST service's name here Add some description v1  ${project.build.directory}/api true      ${phase.generate-documentation}   generate      io.github.robwin swagger2markup-maven-plugin 0.9.3  ${project.build.directory}/api ${generated.asciidoc.directory}  asciidoc    ${phase.generate-documentation}  process-swagger      org.asciidoctor asciidoctor-maven-plugin 1.5.3   org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.11   org.jruby jruby-complete 1.7.21    ${asciidoctor.input.directory}  swagger.adoc  book left 2 ${generated.asciidoc.directory}      asciidoc-to-html ${phase.generate-documentation}  process-asciidoc   html5 ${generated.html.directory}     asciidoc-to-pdf ${phase.generate-documentation}  process-asciidoc   pdf ${generated.pdf.directory}      

    Le plugin asciidoctor suppose l’existence d’un fichier .adoc sur lequel travailler. Vous pouvez en créer un qui collecte simplement ceux qui ont été créés par le plug-in 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 de guerre, vous devez vous assurer qu’il est présent au niveau supérieur – les fichiers statiques du dossier WEB-INF ne seront pas diffusés. Vous pouvez le faire dans le plugin maven-war-plugin:

      maven-war-plugin  WebContent false   ${generated.html.directory}    ${generated.pdf.directory}      

    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.

    Bien que la solution d’Amaan Mohammed semble fonctionner, il existe un moyen plus simple d’y parvenir. Jetez un coup d’oeil à swagger2markup-cli .

    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. Il gère beaucoup mieux la largeur du papier que l’impression à partir de editor2.swagger.io, où les barres de défilement masquent des parties du contenu.