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

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

Sin embargo, solo se puede acceder a este servicio de Swagger 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!

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

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

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

Usé Swagger 2 para implementar la documentación.

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: swagger-maven-plugin
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 del 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 asciidoctor asume la existencia de un archivo .adoc para trabajar. Puede crear uno que simplemente recopile los que fueron 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 de la carpeta WEB-INF no se servirán. Puede hacer esto en el plugin 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>

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

Creé un sitio web https://www.swdoc.org/ que trata específicamente el problema. Entonces automatiza la swagger.json -> Asciidoc, Asciidoc -> pdftransformación como se sugiere en las respuestas. El beneficio de esto es que no necesita seguir los procedimientos de instalación. Acepta un documento de especificaciones en forma de url o simplemente un json sin formato. El proyecto está escrito en C # y su página es https://github.com/Irdis/SwDoc

EDITAR

Podría ser una buena idea validar sus especificaciones json aquí: http://editor.swagger.io/ si tiene algún problema con SwDoc, como si el pdf se genera incompleto.

Consulte https://mrin9.github.io/RapiPdf, un elemento personalizado con muchas funciones de personalización y localización.

Descargo de responsabilidad: soy el autor de este paquete

Para mí, la solución más sencilla 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 ocultan partes del contenido.