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
<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.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
<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
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
# 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 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:
- Wählen Sie eine Swagger-Integrationsmethode, die zum Technologie-Stack Ihres Projekts passt
- Entwerfen und schreiben Sie API-Dokumentationsannotationen oder -kommentare sorgfältig
- Passen Sie die Swagger UI-Oberfläche und -Stile nach Bedarf an
- Branding hinzufügen, um die Dokumentation professioneller zu machen
- Geeignete Methoden für die Veröffentlichung und den Export von Dokumentation wählen
- 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