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

1. Обзор

В этом руководстве мы познакомимся с различными способами создания PDF-файла из документации Swagger API. Чтобы ознакомиться со Swagger, обратитесь к нашему руководству по настройке Swagger 2 с помощью Spring REST API .

2. Создайте PDF с помощью плагинов Maven

Первое решение для создания PDF-файла из документации Swagger API основано на наборе подключаемых модулей Maven. При таком подходе мы получим файл PDF при создании проекта Java.

Шаги для создания желаемого PDF-файла включают в себя применение нескольких подключаемых модулей в определенном порядке во время сборки Maven . Плагины должны быть настроены на выбор ресурсов и распространение выходных данных предыдущих фаз в качестве входных данных следующей фазы. Итак, давайте посмотрим, как работает каждый из них.

2.1. Плагин swagger -maven-plugin

Первый плагин, который мы будем использовать, это swagger-maven-plugin . Этот плагин создает файл swagger.json для нашего REST API :

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
        <apiSource>
            <springmvc>false</springmvc>
        <locations>com.foreach.swagger2pdf.controller.UserController</locations>
        <basePath>/api</basePath>
        <info>
                <title>DEMO REST API</title>
            <description>A simple DEMO project for REST API documentation</description>
            <version>v1</version>
        </info>
        <swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
            <attachSwaggerArtifact>true</attachSwaggerArtifact>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
        <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Нам нужно указать расположение нашего API и определить фазу процесса сборки, во время которой плагин создает файл swagger.json . Здесь, в теге выполнения , мы указали, что он должен делать это на этапе пакета .

2.2. Плагин swagger2markup-maven- plugin

Второй нужный нам плагин — это swagger2markup-maven-plugin . Он использует выходные данные swagger.json предыдущего плагина в качестве входных данных для создания Asciidoc :

<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>
        <markupLanguage>asciidoc</markupLanguage>
    </configuration>
    <executions>
        <execution>
        <phase>package</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Здесь мы указываем теги inputDirectory и o outputDirectory . Опять же, мы определим пакет как этап сборки для создания Asciidoc для нашего REST API.

2.3. Плагин asciidoctor-maven- plugin

Третий и последний плагин, который мы будем использовать, это asciidoctor-maven-plugin . Как последний из трех плагинов, этот создает PDF-файл из Asciidoc :

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.1</version>
    <dependencies>
        <dependency>
        <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.6.0</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${project.build.outputDirectory}/../asciidoc</sourceDirectory>
        <sourceDocumentName>overview.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>2</toclevels>
            <generated>${generated.asciidoc.directory}</generated>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-pdf</id>
            <phase>package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${project.build.outputDirectory}/api/pdf</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

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

3. Создайте PDF с помощью SwDoc

Swagger to PDF — это онлайн-инструмент, доступный на сайте swdoc.org , который создает документацию API в файле PDF с использованием предоставленной спецификации swagger.json . Он использует конвертер Swagger2Markup и AsciiDoctor .

Принципы аналогичны предыдущим решениям. Во-первых, Swagger2Markup преобразует swagger.json в файлы AsciiDoc. Затем Asciidoctor преобразует эти файлы в модель документа и преобразует их в файл PDF.

Решение простое в использовании и является хорошим выбором, если у нас уже есть документ Swagger 2 API .

Мы можем сгенерировать PDF двумя способами:

• предоставление URL-адреса нашего файла swagger.json
• вставка содержимого нашего файла swagger.json в текстовое поле инструмента

Мы будем использовать документ PetStore API, общедоступный на Swagger .

Для нашей цели мы скопируем файл JSON и вставим его в текстовое поле:

Затем, после того, как мы нажмем кнопку «Создать», мы получим документацию в формате PDF:

4. Вывод

В этом кратком руководстве мы обсудили два способа создания PDF-файла из документации Swagger API.

Первый подход основан на плагинах Maven. Мы можем использовать три плагина и генерировать документацию REST API при создании приложения.

Второе решение описывает, как создавать PDF-документы с помощью онлайн-инструмента SwDoc. Мы можем либо сгенерировать документацию по ссылке на наш swagger.json, либо вставить содержимое файла JSON в инструмент.

Как всегда, код этих примеров доступен на GitHub .