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

93

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!

pdf  swagger-ui 
— Aman Mohammed
fuente

Respuestas:

39

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

ingrese la descripción de la imagen aquí

— Osify
fuente
¡Sencillo! La documentación sale bastante bien.
— ShaTin
1
Incluso puede elegir entre dos diseños de documentación siempre que haya dos servicios Swagger: editor.swagger.io (nuevo) y editor2.swagger.io (anterior).
— naXa
La interfaz de usuario HTML de bcos swagger efectiva pero con pérdidas tiene varias pestañas, para los parámetros de un método POST / PUT debe elegir entre la pestaña del modelo y la pestaña del valor de ejemplo, luego, en la versión impresa en PDF, una de ellas está oculta para siempre :(
— chrisinmtown
Esto no funcionó para mí. Cada punto final se cortaría con el final de la página (sin importar qué configuración de página utilicé). La siguiente página comenzaría en la parte superior del siguiente bloque de Endpoint. Quizás algo haya cambiado desde que se escribió esta respuesta.
— killa-byte
Todavía veo que es viable, es posible que deba adaptar el margen. Prueba desde editor.swagger.io
— Osify
33

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

Usé Swagger 2 para implementar la documentación.

— Aman Mohammed
fuente
hola, también estoy tratando de generar documentación fuera de línea usando swagger. ¿Puedes generar documentación swagger?
— Sunil Rk
sí, utilicé los proyectos de ejemplo e integré mi código de servicio web en ellos y pude generar la documentación.
— Aman Mohammed
1
¿Podría decirme brevemente cómo puedo integrar mi servicio web a los ejemplos que ha mencionado anteriormente?
— Sunil Rk
El proyecto swagger2markup necesita una entrada JSON de la API REST. Si descarga ese proyecto gradle y cambia el archivo swagger.json con los detalles de su API y luego ejecuta el método JUnit Swagger2MarkupConverterTest: testSwagger2HtmlConversion, debería generar el HTML en la carpeta build / docs / generate / asciidocAsString del proyecto. Entonces, en otras palabras, hay 2 cosas. 1) Primero genere el formato JSON para su API REST usando Swagger Editor. 2) Usando ese formato JSON, puede usar el proyecto swagger2markup para producir documentación HTML independiente de la API
— Aman Mohammed
22

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.

— Hervian
fuente
Hola @Hervian. Gran respuesta. Podría usar tu anser hasta ahora. Tengo dos clases con el mismo nombre pero en paquetes diferentes. Sin embargo, swagger.json contiene la definición de solo uno de ellos. Falta el otro
— edmond
@Hervian Recibí errores hasta que hice lo siguiente 1) Creé el archivo src / main / asciidoc / swagger.adoc con el contenido de arriba. 2) agregó estas propiedades al POM: <phase.generate-documentation> process-classes </phase.generate-documentation> <generate.asciidoc.directory> $ {project.build.directory} / api-gen </ generate. asciidoc.directory> Luego ejecute "mvn install" y no veo ningún error de mvn o plugin pero solo el archivo overview.adoc tiene contenido; los archivos definitions.adoc y paths.adoc permanecen vacíos. Prfa aconsejen.
— chrisinmtown
15

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.

— Irdis
fuente
3
gracias, sí, es bastante bueno, lo uso para mis proyectos de trabajo. Estoy pensando en escribir código para soportar openapi 3.0 en mi tiempo libre.
— Irdis
2
Toda la gloria a los autores de las herramientas en las que se basa, ofc
— Irdis
@Irdis Intenté usar el enlace. Permite analizar el documento Swagger 2.0, pero el documento que estoy proporcionando es de Open API 3.0 y no puede generar el documento.
— hellowahab
Probé swagger 3+ - funciona bien, aunque muestra html sin procesar para comentarios ...
— Sasha Bond
¡Esta es una gran herramienta! Si alguna vez tiene problemas como yo (como el pdf que se genera incompleto), pegue su json aquí: editor.swagger.io para que se valide automáticamente, solucione los problemas y estará listo para volver a la herramienta swdoc y generarlo correctamente esta vez.
— Thales Valias
9

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

— Mrinmoy
fuente
2
¿Acabo de probarlo pero no obtengo una respuesta después de hacer clic en "Generar PDF" con las especificaciones de prueba (tienda de mascotas)?
— imehl
1
@imehl Funciona bien cuando me probé en mac / chrome, mac / firefox, mac / safari y windows / chrome. Esto solo funciona en el navegador web que admite componentes web como Chrome, Firefox y Safari. Si aún tiene problemas, inicie sesión en Github github.com/mrin9/RapiPdf
— Mrinmoy
@Mrinmoy Tuve el mismo problema que imehl, abrió una nueva pestaña pero se cerró inmediatamente (ubuntu 18.04 + firefox / chrome ambos con el mismo resultado). Luego lo hice en Windows y funcionó a la perfección. Gracias por esta herramienta, es increíble.
— Dabux
3
@Dabux nunca probó en ubuntu, pero hay una situación que conozco en la que las personas enfrentan el mismo problema que usted explicó, y es cuando tiene un bloqueador activo o bloqueador de ventanas emergentes en el navegador
— Mrinmoy
@Mrinmoy, tienes razón, tenía un bloqueador de anuncios, fue por eso, no por el sistema operativo.
— Dabux
1

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.

— Simón
fuente
1
Intenté usar esto, pero la impresión a través de la página web agrega varios enlaces y otra información también.
— hellowahab
Sí, debería haberlo mencionado. No fue un problema para mi uso.
— Simon
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.