Documentation d'exportation de Swagger UI

Générer une documentation HTML statique

Utilisation de Swagger2markup

Swagger2markup est un outil qui peut convertir des fichiers Swagger JSON ou YAML en documents AsciiDoc ou Markdown. Combiné avec AsciiDoctor, la documentation peut être convertie au format HTML ou PDF.

Ajouter les dépendances Maven :

Exemple

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

Créez une classe de test pour générer la documentation :

Exemple

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 {
        // Définir le répertoire de sortie
        final String outputDir = "target/asciidoc";
       
        // Configuration Swagger2Markup
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(java.util.Locale.CHINA)
                .withGeneratedExamples()
                .withPathsGroupedBy(io.github.swagger2markup.GroupBy.TAGS)
                .build();

        // Générer des fichiers AsciiDoc à partir de fichiers JSON OpenAPI
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v3/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get(outputDir));
    }
}

Exécutez le test et générez la documentation :

# 生成 AsciiDoc
mvn test

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

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

Générer la documentation PDF

Utilisation d'Asciidoctor-PDF

Sur la base des fichiers AsciiDoc générés précédemment, vous pouvez utiliser Asciidoctor-PDF pour générer la documentation PDF :

1. Modifier la configuration Maven :

Exemple

<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>

Personnaliser le style PDFsrc/main/resources/theme/custom-theme.yml:

Exemple

font:
  catalog:
# Configuration des polices chinoises
    Noto Sans SC:
      normal: NotoSansSC-Regular.ttf
      bold: NotoSansSC-Bold.ttf
      italic: NotoSansSC-Regular.ttf
      bold_italic: NotoSansSC-Bold.ttf
# Configuration de police anglaise
    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

Générer la documentation PDF:

mvn asciidoctor:process-asciidoc@pdf

Utiliser des outils pour exporter directement

Utilisation de l'outil wkhtmltopdf

1. Installer wkhtmltopdf:

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# CentOS/RHEL
sudo yum install wkhtmltopdf

# macOS
brew install wkhtmltopdf

2. Créer un script d'exportexport-docs.sh:

#

Exemple

!/bin/bash

# Définir les variables
SWAGGER_URL="http://localhost:8080/swagger-ui/index.html"
OUTPUT_DIR="./api-docs"
FILENAME="api-documentation.pdf"
HTML_FILENAME="api-documentation.html"

# Créer le répertoire de sortie
mkdir -p $OUTPUT_DIR

# Utiliser curl pour télécharger la documentation HTML
echo Téléchargement du HTML de Swagger UI...
curl -s $SWAGGER_URL > $OUTPUT_DIR/$HTML_FILENAME

# Utiliser wkhtmltopdf pour générer le PDF
echo Génération de la documentation PDF...
wkhtmltopdf \
  --enable-javascript \
  --javascript-delay 5000 \
  --no-stop-slow-scripts \
  --page-size A4 \
  --title Documentation de l'API \
  --margin-top 20 \
  --margin-right 20 \
  --margin-bottom 20 \
  --margin-left 20 \
  --header-line \
  --header-center Centre de documentation de l'API \
  --footer-line \
  --footer-center Page [page] / [topage] \
  --footer-right Date de génération :$(date +%Y-%m-%d)" \
  $OUTPUT_DIR/$HTML_FILENAME $OUTPUT_DIR/$FILENAME

echo Document généré :
echo "HTML : $OUTPUT_DIR/$HTML_FILENAME"
echo "PDF: $OUTPUT_DIR/$FILENAME"

3. Exécuter le script :

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

Exporter le PDF avec Puppeteer

Pour les environnements Node.js, vous pouvez utiliser Puppeteer pour exporter en PDF.

1. Créer un script d'exportexport-pdf.js:

Exemple

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

(async () => {
  // Créer le répertoire de sortie
  const outputDir = path.join(__dirname, 'api-docs');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir);
  }

  // Lancer le navigateur
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
 
  // Visiter la page Swagger UI
  await page.goto('http://localhost:8080/swagger-ui/index.html', {
    waitUntil: 'networkidle0',
    timeout: 60000
  });

  // Attendre la fin du chargement de Swagger UI
  await page.waitForSelector('.swagger-ui .information-container', { timeout: 10000 });
 
  // Développer tous les nœuds API
  await page.evaluate(() => {
    document.querySelectorAll('.opblock').forEach(el => {
      if (!el.classList.contains('is-open')) {
        el.querySelector('.opblock-summary').click();
      }
    });
  });

  // Attendre la fin de l'animation de dépliage
  await page.waitForTimeout(2000);
 
  // Ajouter des styles personnalisés pour l'en-tête et le pied de page
  await page.addStyleTag({
    content: `
      @page {
        margin: 20mm 15mm;
      }
      .en-tête-de page {
        width: 100%;
        text-align: center;
        font-size: 16px;
        color: #333;
        padding: 10px 0;
        border-bottom: 1px solid #ddd;
      }
      .pied-de page {
        width: 100%;
        text-align: center;
        font-size: 12px;
        color: #666;
        padding: 10px 0;
        border-top: 1px solid #ddd;
      }
    `
  });

  // Générer un PDF
  await page.pdf({
    path: path.join(outputDir, 'api-documentation.pdf'),
    format: 'A4',
    printBackground: true,
    displayHeaderFooter: true,
    headerTemplate: `<div class="page-header">Centre de documentation de l'API</div>`,
    footerTemplate: `<div class="page-footer">
                       <span>Numéro de page<span class="pageNumber"></span> / <span class="totalPages"></span></span>
                       <span style="margin-left: 20px;">Date de génération: ${new Date().toLocaleDateString()}</span>
                     </div>`,
    margin: {
      top: '40px',
      bottom: '40px',
      left: '20px',
      right: '20px'
    }
  });

  // Générer le HTML
  const htmlContent = await page.content();
  fs.writeFileSync(path.join(outputDir, 'api-documentation.html'), htmlContent);

  // Fermer le navigateur
  await browser.close();
 
  console.log('Document généré dans le répertoire :', outputDir);
})();

2. Installez les dépendances et exécutez :

npm install puppeteer
node export-pdf.js

Résumé

Swagger UI est un puissant outil de documentation d'API. Avec une configuration et une utilisation appropriées, il peut grandement améliorer l'utilisabilité des API et l'efficacité du développement.

À travers le contenu ci-dessus, nous avons découvert les concepts de base, les méthodes d'intégration, la rédaction de documentation, la configuration personnalisée, la publication de documentation, la personnalisation du style et l'exportation de documentation de Swagger UI.

Retenez les points clés suivants :

  1. Choisissez une méthode d'intégration Swagger adaptée à la pile technologique de votre projet
  2. Concevez et rédigez soigneusement les annotations ou commentaires de documentation d'API
  3. Personnalisez l'interface et les styles de Swagger UI selon vos besoins
  4. Ajoutez une image de marque pour rendre la documentation plus professionnelle
  5. Choisissez des méthodes appropriées de publication et d'exportation de documentation
  6. Suivez les meilleures pratiques pour garantir l'exactitude et la sécurité de la documentation

En utilisant Swagger UI de manière appropriée, vous pouvez fournir une documentation professionnelle et interactive pour votre API, ce qui facilite sa compréhension et son utilisation.

Autres extensions