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

91

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!

pdf  swagger-ui 
— Aman Mohammed
fonte

Respostas:

39

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

insira a descrição da imagem aqui

— Osify
fonte
Simples! A documentação sai muito bem.
— ShaTin
1
Você pode até escolher entre dois designs de documentação, desde que haja dois serviços Swagger: editor.swagger.io (novo) e editor2.swagger.io (anterior)!
— naXa
A interface de usuário HTML swagger de bcos eficaz, mas com perdas, tem várias guias, para os parâmetros de um método POST / PUT você deve escolher entre a guia de modelo e a guia de valor de exemplo, então, na versão impresso em PDF, uma delas fica oculta para sempre :(
— chrisinmtown
Isso não funcionou para mim. Cada ponto de extremidade seria cortado com o final da página (independentemente da configuração de página que usei). A próxima página então começaria no topo do próximo bloco de Endpoint. Talvez algo tenha mudado desde que esta resposta foi escrita.
— killa-byte
Ainda vejo que é viável, talvez você precise adaptar a margem. Tente em editor.swagger.io
— Osify
33

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.

— Aman Mohammed
fonte
Olá, também estou tentando gerar documentação offline usando swagger. Você consegue gerar documentação swagger ??
— Sunil Rk
sim, usei os projetos de exemplo e integrei meu código de webservice neles e consegui gerar a documentação.
— Aman Mohammed
1
Você pode, por favor, me dizer, resumidamente, como posso integrar meu serviço web aos exemplos que você mencionou acima.
— Sunil Rk
O projeto swagger2markup precisa de uma entrada JSON da API REST. Se você baixar esse projeto gradle e alterar o arquivo swagger.json com os detalhes da API e, em seguida, executar o método Swagger2MarkupConverterTest JUnit: testSwagger2HtmlConversion, ele deve gerar o HTML para você na pasta build / docs / generated / asciidocAsString do projeto. Em outras palavras, existem 2 coisas. 1) Primeiro gere o formato JSON para sua API REST usando o Editor Swagger. 2) Usando esse formato JSON, você pode usar o projeto swagger2markup para produzir documentação HTML autônoma da API
— Aman Mohammed
21

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.

— Herviano
fonte
Olá, @Hervian. Ótima resposta. Eu poderia usar seu anser até agora. Tenho duas classes com o mesmo nome, mas em pacotes diferentes. No entanto, o swagger.json contém a definição para apenas um deles. O outro está faltando
— edmond
@Hervian Recebi erros até que fiz o seguinte 1) criei o arquivo src / main / asciidoc / swagger.adoc com o conteúdo de cima. 2) adicionadas essas propriedades ao POM: <phase.generate-documentation> process-classes </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated. asciidoc.directory> Em seguida, execute "mvn install" e não vejo erros de mvn ou plug-in, mas apenas o arquivo overview.adoc tem conteúdo; os arquivos settings.adoc e paths.adoc permanecem vazios. Por favor, avise.
— chrisinmtown
13

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.

— Irdis
fonte
3
obrigado, sim, é muito bom, eu uso para meus projetos de trabalho. Estou pensando em escrever algum código para suportar o openapi 3.0 nas minhas horas vagas.
— Irdis
2
Toda a glória para os autores das ferramentas nas quais ela depende, ofc
— Irdis
@Irdis tentei usar o link. Ele permite que o doc do Swagger 2.0 seja analisado, mas o documento que estou fornecendo é do Open API 3.0 e não é possível gerar o documento.
— hellowahab
Tentei swagger 3+ - funciona bem, mas mostra HTML bruto para comentários ...
— Sasha Bond,
Essa é uma ótima ferramenta! Se você já teve problemas como os meus (como pdf sendo gerado incompleto), cole seu json aqui: editor.swagger.io para ser validado automaticamente, conserte os problemas e você estará pronto para voltar à ferramenta swdoc e gerá-lo corretamente desta vez.
— Thales Valias
7

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

— Mrinmoy
fonte
2
acabei de testar, mas não obtenho uma resposta após clicar em "Gerar PDF" com as especificações de teste (petstore).
— imehl
1
@imehl Funcionou bem quando testei no mac / chrome, mac / firefox, mac / safari e windows / chrome. Isso só funciona em um navegador que suporte componentes da web como Chrome, Firefox e Safari. Se ainda estiver enfrentando problemas, registre-os no Github github.com/mrin9/RapiPdf
— Mrinmoy
@Mrinmoy eu tive o mesmo problema que o imehl, ele abriu uma nova aba mas fechou imediatamente (ubuntu 18.04 + firefox / chrome ambos o mesmo resultado). Então eu fiz no windows e funcionou como um encanto. Obrigado por esta ferramenta, é incrível.
— Dabux de
3
O @Dabux nunca testou no ubuntu, mas há uma situação que eu conheço em que as pessoas enfrentam o mesmo problema que você explicou, e é quando você tem qualquer bloqueador ativo ou bloqueador de pop-up no navegador
— Mrinmoy
@Mrinmoy você tem razão, coloquei um bloqueador de anúncios, foi por causa disso, não por causa do sistema operacional.
— Dabux
1

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.

— Simon
fonte
1
tentei usar isso, mas a impressão via página da web adiciona vários links e outras informações também.
— hellowahab
Sim, eu deveria ter mencionado isso. Não foi um problema para meu uso.
— Simon
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.