Swagger UI Export-Dokumentation

Statische HTML-Dokumentation generieren

Verwendung von Swagger2markup

Swagger2markup ist ein Werkzeug, das Swagger-JSON- oder YAML-Dateien in AsciiDoc- oder Markdown-Dokumente umwandeln kann. In Kombination mit AsciiDoctor kann die Dokumentation in das HTML- oder PDF-Format konvertiert werden.

Maven-Abhängigkeiten hinzufügen:

Beispiel

<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> <!-- oder 'pdf' -->
                <attributes>
                    <toc>left</toc>
                    <toclevels>3</toclevels>
                </attributes>
            </configuration>
        </plugin>
    </plugins>
</build>

Erstellen Sie eine Testklasse zum Generieren der Dokumentation:

Beispiel

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 {
        // Ausgabeverzeichnis festlegen
        final String outputDir = "target/asciidoc";
       
        // Swagger2Markup-Konfiguration
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(java.util.Locale.CHINA)
                .withGeneratedExamples()
                .withPathsGroupedBy(io.github.swagger2markup.GroupBy.TAGS)
                .build();

        // AsciiDoc-Dateien aus OpenAPI-JSON-Dateien generieren
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v3/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get(outputDir));
    }
}

Führen Sie den Test aus und generieren Sie die Dokumentation:

# 生成 AsciiDoc
mvn test

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

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

PDF-Dokumentation generieren

Mit Asciidoctor-PDF

Basierend auf den zuvor generierten AsciiDoc-Dateien können Sie Asciidoctor-PDF verwenden, um PDF-Dokumentation zu generieren:

1. Maven-Konfiguration ändern:

Beispiel

<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-Stil anpassensrc/main/resources/theme/custom-theme.yml:

Beispiel

font:
  catalog:
# Chinesische Schriftartkonfiguration
    Noto Sans SC:
      normal: NotoSansSC-Regular.ttf
      bold: NotoSansSC-Bold.ttf
      italic: NotoSansSC-Regular.ttf
      bold_italic: NotoSansSC-Bold.ttf
# Englische Schriftkonfiguration
    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

Basis:
  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-Dokumentation generieren:

mvn asciidoctor:process-asciidoc@pdf

Werkzeuge zum direkten Exportieren verwenden

Verwendung des wkhtmltopdf-Tools

1. wkhtmltopdf installieren:

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# CentOS/RHEL
sudo yum install wkhtmltopdf

# macOS
brew install wkhtmltopdf

2. Ein Exportskript erstellenexport-docs.sh:

#

Beispiel

!/bin/bash

# Variablen setzen
SWAGGER_URL="http://localhost:8080/swagger-ui/index.html"
OUTPUT_DIR="./api-docs"
FILENAME="api-documentation.pdf"
HTML_FILENAME="api-documentation.html"

# Ausgabeverzeichnis erstellen
mkdir -p $OUTPUT_DIR

# Mit curl HTML-Dokumentation herunterladen
echo Swagger UI HTML wird heruntergeladen...
curl -s $SWAGGER_URL > $OUTPUT_DIR/$HTML_FILENAME

# Mit wkhtmltopdf PDF generieren
echo PDF-Dokumentation wird erstellt...
wkhtmltopdf \
  --enable-javascript \
  --javascript-delay 5000 \
  --no-stop-slow-scripts \
  --page-size A4 \
  --title API-Dokumentation \
  --margin-top 20 \
  --margin-right 20 \
  --margin-bottom 20 \
  --margin-left 20 \
  --header-line \
  --header-center API-Dokumentationszentrum \
  --footer-line \
  --footer-center Seite [page] / [topage] \
  --footer-right Erstellungsdatum:$(date +%Y-%m-%d)" \
  $OUTPUT_DIR/$HTML_FILENAME $OUTPUT_DIR/$FILENAME

echo Dokument erstellt:
echo "HTML: $OUTPUT_DIR/$HTML_FILENAME"
echo "PDF: $OUTPUT_DIR/$FILENAME"

3. Führen Sie das Skript aus:

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

PDF mit Puppeteer exportieren

Für Node.js-Umgebungen können Sie Puppeteer verwenden, um PDF zu exportieren.

1. Erstellen Sie ein Exportskriptexport-pdf.js:

Beispiel

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

(async () => {
  // Ausgabeverzeichnis erstellen
  const outputDir = path.join(__dirname, 'api-docs');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir);
  }

  // Browser starten
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
 
  // Swagger-UI-Seite aufrufen
  await page.goto('http://localhost:8080/swagger-ui/index.html', {
    waitUntil: 'networkidle0',
    timeout: 60000
  });

  // Warten, bis Swagger UI fertig geladen ist
  await page.waitForSelector('.swagger-ui .information-container', { timeout: 10000 });
 
  // Alle API-Knoten erweitern
  await page.evaluate(() => {
    document.querySelectorAll('.opblock').forEach(el => {
      if (!el.classList.contains('is-open')) {
        el.querySelector('.opblock-summary').click();
      }
    });
  });

  // Warten, bis die Erweiterungsanimation abgeschlossen ist
  await page.waitForTimeout(2000);
 
  // Benutzerdefinierte Header- und Footer-Stile hinzufügen
  await page.addStyleTag({
    content: `
      @page {
        margin: 20mm 15mm;
      }
      .Seiten-kopf {
        width: 100%;
        text-align: center;
        font-size: 16px;
        color: #333;
        padding: 10px 0;
        border-bottom: 1px solid #ddd;
      }
      .Seiten-fuß {
        width: 100%;
        text-align: center;
        font-size: 12px;
        color: #666;
        padding: 10px 0;
        border-top: 1px solid #ddd;
      }
    `
  });

  // PDF generieren
  await page.pdf({
    path: path.join(outputDir, 'api-documentation.pdf'),
    format: 'A4',
    printBackground: true,
    displayHeaderFooter: true,
    headerTemplate: `<div class="page-header">API-Dokumentationszentrum</div>`,
    footerTemplate: `<div class="page-footer">
                       <span>Seitenzahl<span class="pageNumber"></span> / <span class="totalPages"></span></span>
                       <span style="margin-left: 20px;">Erstellungsdatum: ${new Date().toLocaleDateString()}</span>
                     </div>`,
    margin: {
      top: '40px',
      bottom: '40px',
      left: '20px',
      right: '20px'
    }
  });

  // HTML generieren
  const htmlContent = await page.content();
  fs.writeFileSync(.join(outputDir, 'api-documentation.html'), htmlContent);

  // Browser schließen
  await browser.close();
 
  console.log('Dokument generiert im Verzeichnis:', outputDir);
})();

2. Abhängigkeiten installieren und ausführen:

npm install puppeteer
node export-pdf.js

Zusammenfassung

Swagger UI ist ein leistungsstarkes API-Dokumentationstool. Mit der richtigen Konfiguration und Nutzung kann es die API-Nutzbarkeit und Entwicklungseffizienz erheblich verbessern.

Durch die oben genannten Inhalte haben wir die grundlegenden Konzepte, Integrationsmethoden, Dokumentationserstellung, benutzerdefinierte Konfiguration, Dokumentationsveröffentlichung, Stilanpassung und Dokumentationsexport von Swagger UI kennengelernt.

Beachten Sie die folgenden wichtigen Punkte:

  1. Wählen Sie eine Swagger-Integrationsmethode, die zum Technologie-Stack Ihres Projekts passt
  2. Entwerfen und schreiben Sie API-Dokumentationsannotationen oder -kommentare sorgfältig
  3. Passen Sie die Swagger UI-Oberfläche und -Stile nach Bedarf an
  4. Branding hinzufügen, um die Dokumentation professioneller zu machen
  5. Geeignete Methoden für die Veröffentlichung und den Export von Dokumentation wählen
  6. Befolgen Sie Best Practices, um Genauigkeit und Sicherheit der Dokumentation zu gewährleisten

Durch die angemessene Verwendung von Swagger UI können Sie eine professionelle, interaktive Dokumentation für Ihre API bereitstellen, die einfacher zu verstehen und zu nutzen ist.

Weitere Erweiterungen