Создание PDF из документации Swagger API

удобном виде: С Помощью Браузера Печать / Предварительный Просмотр

1. скрыть панель редактора
2. предварительный просмотр (я использовал firefox, другие также отлично)
3. изменить настройки страницы и печать в формате pdf

вы можете изменить свой проект REST, чтобы создать необходимые статические документы (html, pdf и т. д.) При создании проекта.

Если у вас есть проект Java Maven, вы можете использовать фрагмент POM ниже. Он использует ряд плагинов для создания pdf и html документации (из ресурсов REST проекта).

1. rest-api - > swagger.json: swagger-maven-plugin
2. чванство.json - > Asciidoc : swagger2markup-maven-plugin
3. Asciidoc - > PDF: asciidoctor-maven-plugin

обратите внимание, что порядок выполнения имеет значение, так как выход одного плагина становится входом для следующего:

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

плагин asciidoctor предполагает существование an .файл adoc для работы. Вы можете создать тот, который просто собирает те, которые были созданы плагином swagger2markup:

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

Если вы хотите, чтобы ваш сгенерированный html-документ, чтобы стать частью вашего файла war, вы должны убедиться, что он присутствует на верхнем уровне - статические файлы в папке WEB-INF не будут обслуживаться. Вы можете сделать это в 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>

плагин war работает над сгенерированной документацией - таким образом, вы должны убедиться, что эти плагины были выполнены на более ранней стадии.

хотя решение Амана Мохаммеда выглядит так, как будто оно будет работать, есть более простой способ сделать это. Взгляните на swagger2markup-cli.

для меня самым простым решением было импортировать swagger (v2) в Postman, а затем перейти в веб-представление. Там вы можете выбрать "один столбец" вид и использовать браузер для печати в PDF. Не автоматизированное / интегрированное решение, но хорошее для одноразового использования. Он обрабатывает ширину бумаги намного лучше, чем печать с editor2.swagger.io, где полосы прокрутки заставляют части содержимого быть скрытыми.