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();

        // OpenAPI JSON ファイルから AsciiDoc ファイルを生成
        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>

PDF スタイルをカスタマイズsrc/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 "Swagger UI HTML をダウンロード中..."
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

Puppeteer を使用して PDF をエクスポート

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 にプロフェッショナルでインタラクティブなドキュメントを提供し、API をより理解しやすく、使いやすくすることができます。

その他の拡張