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

Question 1

Я використовував інтерфейс Swagger для відображення своїх веб-служб REST та розміщував їх на сервері.

Однак ця служба Swagger доступна лише на певному сервері. Якщо я хочу працювати в автономному режимі, хтось знає, як я можу створити статичний PDF за допомогою інтерфейсу Swagger та працювати з ним? Крім того, PDF-файлом легко поділитися з людьми, які не мають доступу до сервера.

Дуже дякую!

Question 2

Зручний спосіб: Використання браузерного друку / попереднього перегляду

Приховати область редактора
Попередній перегляд друку (я використовував firefox, інші також чудово)
Змініть налаштування сторінки та роздрукуйте у форматі PDF

Question 3

Я придумав спосіб, використовуючи https://github.com/springfox/springfox та https://github.com/RobWin/swagger2markup

Використовував Swagger 2 для реалізації документації.

Question 4

Ви можете змінити свій проект 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'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 передбачає існування файлу .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>

Військовий плагін працює над згенерованою документацією - як такий, ви повинні переконатися, що ці плагіни були запущені на попередній стадії.

Question 5

Я створив веб-сайт https://www.swdoc.org/, який конкретно вирішує проблему. Отже, це автоматизує swagger.json -> Asciidoc, Asciidoc -> pdfтрансформацію, як пропонується у відповідях. Перевага цього полягає в тому, що вам не потрібно проходити процедури встановлення. Він приймає специфікаційний документ у формі url або просто необроблений json. Проект написаний на C #, а його сторінка - https://github.com/Irdis/SwDoc

РЕДАГУВАТИ

Можливо, буде гарною ідеєю перевірити свої специфікації json тут: http://editor.swagger.io/, якщо у вас є якісь проблеми із SwDoc, наприклад, файл PDF створюється неповним.

Question 6

Оформити замовлення https://mrin9.github.io/RapiPdf користувацький елемент із великою кількістю можливостей налаштування та локалізації.

Застереження: Я є автором цього пакету

Question 7

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