Gerar PDF a partir da documentação da API Swagger

Usei a IU do Swagger para exibir meus serviços da web REST e hospedei-os em um servidor.

No entanto, este serviço do Swagger só pode ser acessado em um servidor específico. Se eu quiser trabalhar offline, alguém sabe como posso criar um PDF estático usando a IU do Swagger e trabalhar com ele? Além disso, um PDF é fácil de compartilhar com pessoas que não têm acesso ao servidor.

Muito Obrigado!

Maneira prática: usando a impressão / visualização do navegador

1. Ocultar painel do editor
2. Visualizar impressão (usei o firefox, outros também estão bem)
3. Altere a configuração da página e imprima em pdf

Eu descobri uma maneira usando https://github.com/springfox/springfox e https://github.com/RobWin/swagger2markup

Usei o Swagger 2 para implementar a documentação.

Você pode modificar seu projeto REST, de modo a produzir os documentos estáticos necessários (html, pdf etc) ao construir o projeto.

Se você tem um projeto Java Maven, pode usar o snippet pom abaixo. Ele usa uma série de plugins para gerar uma documentação em pdf e html (dos recursos REST do projeto).

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

Esteja ciente de que a ordem de execução é importante, já que a saída de um plugin torna-se a entrada do próximo:

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

O plugin asciidoctor pressupõe a existência de um arquivo .adoc para trabalhar. Você pode criar um que simplesmente reúna aqueles que foram criados pelo plug-in swagger2markup:

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

Se você deseja que seu documento html gerado se torne parte de seu arquivo war, você deve ter certeza de que ele está presente no nível superior - arquivos estáticos na pasta WEB-INF não serão servidos. Você pode fazer isso no plugin 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>

O plug-in war funciona na documentação gerada - como tal, você deve certificar-se de que esses plug-ins foram executados em uma fase anterior.

Criei um site https://www.swdoc.org/ que trata especificamente do problema. Portanto, ele automatiza a swagger.json -> Asciidoc, Asciidoc -> pdftransformação conforme sugerido nas respostas. A vantagem disso é que você não precisa seguir os procedimentos de instalação. Ele aceita um documento de especificação na forma de url ou apenas um json bruto. O projeto é escrito em C # e sua página é https://github.com/Irdis/SwDoc

EDITAR

Pode ser uma boa ideia validar suas especificações json aqui: http://editor.swagger.io/ se você estiver tendo problemas com o SwDoc, como o pdf sendo gerado incompleto.

Confira https://mrin9.github.io/RapiPdf um elemento personalizado com bastante personalização e recurso de localização.

Isenção de responsabilidade: eu sou o autor deste pacote

Para mim, a solução mais fácil era importar swagger (v2) para o Postman e ir para a visualização da web. Lá você pode escolher a visualização em "coluna única" e usar o navegador para imprimir em PDF. Não é uma solução automatizada / integrada, mas boa para uso único. Ele lida com a largura do papel muito melhor do que imprimir em editor2.swagger.io, onde as barras de rolagem fazem com que partes do conteúdo fiquem ocultas.