Экспорт документации Swagger UI

Генерация статической HTML-документации

Использование Swagger2markup

Swagger2markup — это инструмент, который может преобразовывать файлы Swagger JSON или YAML в документы AsciiDoc или Markdown. В сочетании с AsciiDoctor документацию можно преобразовать в формат HTML или PDF.

Добавьте зависимости Maven:

Пример

<dependencies>
    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>2.2.2</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctorj-pdf</artifactId>
                    <version>1.6.2</version>
                </dependency>
            </dependencies>
            <configuration>
                <sourceDirectory>target/asciidoc</sourceDirectory>
                <outputDirectory>target/generated-docs</outputDirectory>
                <backend>html5</backend> <!-- или 'pdf' -->
                <attributes>
                    <toc>left</toc>
                    <toclevels>3</toclevels>
                </attributes>
            </configuration>
        </plugin>
    </plugins>
</build>

Создайте тестовый класс для генерации документации:

Пример

import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.URL;
import java.nio.file.Paths;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class SwaggerDocumentationTest {

    @Test
    public void generateAsciiDoc() throws Exception {
        // Установить выходной каталог
        final String outputDir = "target/asciidoc";
       
        // Конфигурация Swagger2Markup
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(java.util.Locale.CHINA)
                .withGeneratedExamples()
                .withPathsGroupedBy(io.github.swagger2markup.GroupBy.TAGS)
                .build();

        // Сгенерировать файлы AsciiDoc из JSON-файлов OpenAPI
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v3/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get(outputDir));
    }
}

Запустите тест и сгенерируйте документацию:

# 生成 AsciiDoc
mvn test

# 将 AsciiDoc 转换为 HTML
mvn asciidoctor:process-asciidoc

# 生成的文档位于 target/generated-docs 目录

Сгенерировать PDF-документацию

Использование Asciidoctor-PDF

На основе ранее сгенерированных файлов AsciiDoc вы можете использовать Asciidoctor-PDF для генерации PDF-документации:

1. Измените конфигурацию Maven:

Пример

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.2</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.6.2</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>target/asciidoc</sourceDirectory>
        <outputDirectory>target/generated-docs</outputDirectory>
        <backend>pdf</backend>
        <attributes>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <icons>font</icons>
            <source-highlighter>coderay</source-highlighter>
            <pagenums>true</pagenums>
            <pdf-stylesdir>${project.basedir}/src/main/resources/theme</pdf-stylesdir>
            <pdf-style>custom</pdf-style>
            <pdf-fontsdir>${project.basedir}/src/main/resources/fonts</pdf-fontsdir>
        </attributes>
    </configuration>
</plugin>

Настроить стиль PDFsrc/main/resources/theme/custom-theme.yml:

Пример

font:
  catalog:
# Конфигурация китайского шрифта
    Noto Sans SC:
      normal: NotoSansSC-Regular.ttf
      bold: NotoSansSC-Bold.ttf
      italic: NotoSansSC-Regular.ttf
      bold_italic: NotoSansSC-Bold.ttf
# Конфигурация английского шрифта
    Roboto:
      normal: Roboto-Regular.ttf
      bold: Roboto-Bold.ttf
      italic: Roboto-Italic.ttf
      bold_italic: Roboto-BoldItalic.ttf
  fallbacks:
    - Noto Sans SC
    - Roboto

page:
  layout: portrait
  margin: [0.75in, 1in, 0.75in, 1in]
  size: A4

base:
  font_color: #333333
  font_family: Noto Sans SC
  font_size: 10
  line_height_length: 17
  line_height: $base_line_height_length / $base_font_size

title_page:
  align: center
  logo:
    image: image:logo.png[pdfwidth=60%]
  title:
    top: 40%
    font_size: 24
    font_color: #262626
  subtitle:
    font_size: 18
    font_style: bold_italic
    font_color: #666666
  authors:
    font_size: 14
    font_color: #181818
  revision:
    font_size: 12
    font_color: #181818

header:
  height: 0.75in
  line_height: 1
  border_color: #dddddd
  border_width: 0.25
  font_size: 10
  background_color: #f5f5f5
  padding: [4, 4, 4, 4]
  vertical_align: middle

footer:
  height: 0.75in
  line_height: 1
  border_color: #dddddd
  border_width: 0.25
  font_size: 10
  padding: [4, 4, 4, 4]
  vertical_align: middle

heading:
  font_color: #262626
  font_family: Roboto
  h1_font_size: 18
  h2_font_size: 16
  h3_font_size: 14
  h4_font_size: 12
  h5_font_size: 10
  h6_font_size: 10
  line_height: 1.2
  margin_bottom: $base_line_height_length

link:
  font_color: #1565C0

code:
  font_family: Courier
  font_size: 9
  background_color: #f5f5f5
  border_color: #dddddd
  border_radius: 4

Сгенерировать PDF-документацию:

mvn asciidoctor:process-asciidoc@pdf

Используйте инструменты для прямого экспорта

Использование инструмента wkhtmltopdf

1. Установите wkhtmltopdf:

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# CentOS/RHEL
sudo yum install wkhtmltopdf

# macOS
brew install wkhtmltopdf

2. Создайте скрипт экспортаexport-docs.sh:

#

Пример

!/bin/bash

# Задайте переменные
SWAGGER_URL="http://localhost:8080/swagger-ui/index.html"
OUTPUT_DIR="./api-docs"
FILENAME="api-documentation.pdf"
HTML_FILENAME="api-documentation.html"

# Создать выходной каталог
mkdir -p $OUTPUT_DIR

# Используйте curl для скачивания HTML-документации
echo Скачивание HTML Swagger UI...
curl -s $SWAGGER_URL > $OUTPUT_DIR/$HTML_FILENAME

# Используйте wkhtmltopdf для создания PDF
echo Создание PDF-документации...
wkhtmltopdf \
  --enable-javascript \
  --javascript-delay 5000 \
  --no-stop-slow-scripts \
  --page-size A4 \
  --title Документация API \
  --margin-top 20 \
  --margin-right 20 \
  --margin-bottom 20 \
  --margin-left 20 \
  --header-line \
  --header-center Центр документации API \
  --footer-line \
  --footer-center Страница [page] / [topage] \
  --footer-right Дата генерации:$(date +%Y-%m-%d)" \
  $OUTPUT_DIR/$HTML_FILENAME $OUTPUT_DIR/$FILENAME

echo Документ сгенерирован:
echo "HTML: $OUTPUT_DIR/$HTML_FILENAME"
echo "PDF: $OUTPUT_DIR/$FILENAME"

3. Запустите скрипт:

chmod +x export-docs.sh
./export-docs.sh

Экспорт PDF с помощью Puppeteer

Для сред Node.js можно использовать Puppeteer для экспорта PDF.

1. Создайте скрипт экспортаexport-pdf.js:

Пример

const puppeteer = require('puppeteer');
const path = require('path');
const fs = require('fs');

(async () => {
  // Создать выходной каталог
  const outputDir = path.join(__dirname, 'api-docs');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir);
  }

  // Запустить браузер
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
 
  // Перейти на страницу Swagger UI
  await page.goto('http://localhost:8080/swagger-ui/index.html', {
    waitUntil: 'networkidle0',
    timeout: 60000
  });

  // Дождаться завершения загрузки Swagger UI
  await page.waitForSelector('.swagger-ui .information-container', { timeout: 10000 });
 
  // Развернуть все узлы API
  await page.evaluate(() => {
    document.querySelectorAll('.opblock').forEach(el => {
      if (!el.classList.contains('is-open')) {
        el.querySelector('.opblock-summary').click();
      }
    });
  });

  // Дождаться завершения анимации разворачивания
  await page.waitForTimeout(2000);
 
  // Добавить пользовательские стили шапки и подвала
  await page.addStyleTag({
    content: `
      @page {
        margin: 20mm 15mm;
      }
      .page-header {
        width: 100%;
        text-align: center;
        font-size: 16px;
        color: #333;
        padding: 10px 0;
        border-bottom: 1px solid #ddd;
      }
      .page-footer {
        width: 100%;
        text-align: center;
        font-size: 12px;
        color: #666;
        padding: 10px 0;
        border-top: 1px solid #ddd;
      }
    `
  });

  // Создать PDF
  await page.pdf({
    path: path.join(outputDir, 'api-documentation.pdf'),
    format: 'A4',
    printBackground: true,
    displayHeaderFooter: true,
    headerTemplate: `<div class="page-header">Центр документации API</div>`,
    footerTemplate: `<div class="page-footer">
                       <span>Номер страницы<span class="pageNumber"></span> / <span class="totalPages"></span></span>
                       <span style="margin-left: 20px;">Дата генерации: ${new Date().toLocaleDateString()}</span>
                     </div>`,
    margin: {
      top: '40px',
      bottom: '40px',
      left: '20px',
      right: '20px'
    }
  });

  // Сгенерировать HTML
  const htmlContent = await page.content();
  fs.writeFileSync(path.join(outputDir, 'api-documentation.html'), htmlContent);

  // Закрыть браузер
  await browser.close();
 
  console.log('Документ сгенерирован в каталоге:', outputDir);
})();

2. Установите зависимости и запустите:

npm install puppeteer
node export-pdf.js

Итог

Swagger UI — мощный инструмент документации API. При правильной настройке и использовании он может значительно повысить удобство использования API и эффективность разработки.

Из приведённого выше материала мы узнали об основных концепциях Swagger UI, способах интеграции, написании документации, пользовательской настройке, публикации документации, настройке стиля и экспорте документации.

Запомните следующие ключевые моменты:

  1. Выберите метод интеграции Swagger, подходящий для технологического стека вашего проекта
  2. Тщательно проектируйте и пишите аннотации или комментарии для документации API
  3. Настройте интерфейс и стили Swagger UI по мере необходимости
  4. Добавьте брендирование, чтобы сделать документацию более профессиональной
  5. Выберите подходящие способы публикации и экспорта документации
  6. Следуйте лучшим практикам, чтобы обеспечить точность и безопасность документации

Правильно используя Swagger UI, вы можете предоставить профессиональную интерактивную документацию для вашего API, делая её более понятной и удобной в использовании.

Другие расширения