pdf - validator - swagger2markup

Generar PDF a partir de la documentación de la API Swagger

Question

He utilizado la interfaz de usuario Swagger para mostrar mis servicios web REST y lo alojé en un servidor.

Sin embargo, este servicio de Swagger solo se puede acceder en un servidor en particular. Si quiero trabajar sin conexión, ¿alguien sabe cómo puedo crear un PDF estático usando la interfaz de usuario de Swagger y trabajar con él? Además, un PDF es fácil de compartir con personas que no tienen acceso al servidor.

¡Muchas gracias!

Answer 1

Creé un sitio web https://www.swdoc.org/ que aborda específicamente el problema. Por lo tanto, automatiza la swagger.json -> Asciidoc, Asciidoc -> pdf como se sugiere en las respuestas. El beneficio de esto es que no necesita realizar los procedimientos de instalación. Acepta un documento de especificaciones en forma de url o simplemente un json sin formato. La página del proyecto es https://github.com/Irdis/SwDoc

Answer 2

Descubrí una forma de usar https://github.com/springfox/springfox y https://github.com/RobWin/swagger2markup

Usé Swagger 2 para implementar la documentación.

Answer 3

Manera práctica: uso de impresión / vista previa del navegador

1. Ocultar panel del editor
2. Vista previa de impresión (utilicé Firefox, otros también están bien)
3. Cambie la configuración de su página e imprima a pdf

Answer 4

Para mí, la solución más fácil fue importar swagger (v2) en Postman y luego ir a la vista web. Allí puede elegir la vista de "columna única" y utilizar el navegador para imprimir en pdf. No es una solución automatizada / integrada, pero es buena para un solo uso. Maneja el ancho del papel mucho mejor que imprimir desde editor2.swagger.io, donde las barras de desplazamiento hacen que partes del contenido se oculten.

Answer 5

Puede modificar su proyecto REST para producir los documentos estáticos necesarios (html, pdf, etc.) al construir el proyecto.

Si tiene un proyecto Java Maven, puede usar el fragmento de pom a continuación. Utiliza una serie de complementos para generar un pdf y una documentación html (de los recursos REST del proyecto).

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

Tenga en cuenta que el orden de ejecución es importante, ya que la salida de un complemento se convierte en la entrada a la siguiente:

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

El complemento de asciidoctor supone la existencia de un archivo .adoc para trabajar. Puede crear uno que simplemente recopile los creados por el complemento swagger2markup:

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

Si desea que su documento html generado se convierta en parte de su archivo war, debe asegurarse de que esté presente en el nivel superior: los archivos estáticos en la carpeta WEB-INF no se servirán. Puedes hacer esto en el complemento 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>

El complemento war funciona en la documentación generada, por lo que debe asegurarse de que esos complementos se hayan ejecutado en una fase anterior.