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

Я использовал интерфейс Swagger для отображения моих веб-сервисов REST и размещал его на сервере.

Однако эта служба Swagger может быть доступна только на определенном сервере. Если я хочу работать в автономном режиме, кто-нибудь знает, как я могу создать статический PDF файл с использованием интерфейса Swagger и работать с ним? Кроме того, PDF файл можно легко разделить с людьми, которые не имеют доступа к серверу.

Большое спасибо!

Ответ 1

Я выяснил способ использования https://github.com/springfox/springfox и https://github.com/RobWin/swagger2markup

Используется Swagger 2 для реализации документации.

Ответ 2

Удобный способ: Использование печати/предварительного просмотра браузера

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

Ответ 3

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

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

rest-api → swagger.json: swagger-maven-plugin
swagger.json → Asciidoc: swagger2markup-maven-plugin
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 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 предполагает существование файла .adoc для работы. Вы можете создать тот, который просто собирает те, которые были созданы плагином swagger2markup:

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

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

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

Ответ 4

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

Ответ 5

Я создал веб-сайт https://www.swdoc.org/, специально предназначенный для решения этой проблемы. Таким образом, он автоматизирует преобразование swagger.json -> Asciidoc, Asciidoc -> pdf, как предлагается в ответах. Преимущество этого заключается в том, что вам не нужно проходить процедуры установки. Он принимает документ спецификации в виде URL или просто необработанного JSON. Страница проекта https://github.com/Irdis/SwDoc

Ответ 6

Оформить заказ https://mrin9.github.io/RapiPdf пользовательского элемента с множеством функций настройки и локализации.

Отказ от ответственности: я автор этого пакета

Ответ 7

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