Exportación de documentos Swagger UI

Generar documento HTML estático

Usar Swagger2markup

Swagger2markup es una herramienta que puede convertir archivos Swagger JSON o YAML a documentos AsciiDoc o Markdown. Combinado con AsciiDoctor, puede convertir documentos a formato HTML o PDF.

Agregar dependencia de Maven:

Ejemplo

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

Crear una clase de prueba para generar documentación:

Ejemplo

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

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

Ejecutar la prueba y generar documentación:

# 生成 AsciiDoc
mvn test

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

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

Generar documento PDF

Usar Asciidoctor-PDF

Basándose en los archivos AsciiDoc generados anteriormente, puede usar Asciidoctor-PDF para generar documentos PDF:

1. Modificar la configuración de Maven:

Ejemplo

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

Personalizar el estilo del PDFsrc/main/resources/theme/custom-theme.yml:

Ejemplo

font:
  catalog:
# Configuración de fuente china
    Noto Sans SC:
      normal: NotoSansSC-Regular.ttf
      bold: NotoSansSC-Bold.ttf
      italic: NotoSansSC-Regular.ttf
      bold_italic: NotoSansSC-Bold.ttf
# Configuración de fuente inglesa
    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

Generar documento PDF:

mvn asciidoctor:process-asciidoc@pdf

Usar herramientas para exportar directamente

Usar la herramienta wkhtmltopdf

1. Instalar wkhtmltopdf:

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# CentOS/RHEL
sudo yum install wkhtmltopdf

# macOS
brew install wkhtmltopdf

2. Crear el script de exportaciónexport-docs.sh:

#

Ejemplo

!/bin/bash

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

# Crear directorio de salida
mkdir -p $OUTPUT_DIR

# Usar curl para descargar el documento HTML
echo "Descargando Swagger UI HTML..."
curl -s $SWAGGER_URL > $OUTPUT_DIR/$HTML_FILENAME

# Usar wkhtmltopdf para generar PDF
echo "Generando documento PDF..."
wkhtmltopdf \
  --enable-javascript \
  --javascript-delay 5000 \
  --no-stop-slow-scripts \
  --page-size A4 \
  --title "Documento API" \
  --margin-top 20 \
  --margin-right 20 \
  --margin-bottom 20 \
  --margin-left 20 \
  --header-line \
  --header-center "Centro de documentación API" \
  --footer-line \
  --footer-center "Página [page] / [topage]" \
  --footer-right "Fecha de generación:$(date +%Y-%m-%d)" \
  $OUTPUT_DIR/$HTML_FILENAME $OUTPUT_DIR/$FILENAME

echo "Documento generado:"
echo "HTML: $OUTPUT_DIR/$HTML_FILENAME"
echo "PDF: $OUTPUT_DIR/$FILENAME"

3. Ejecutar el script:

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

Exportar PDF con Puppeteer

Para entornos Node.js, puede usar Puppeteer para exportar PDF.

1. Crear el script de exportaciónexport-pdf.js:

Ejemplo

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

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

  // Iniciar el navegador
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
 
  // Acceder a la página de Swagger UI
  await page.goto('http://localhost:8080/swagger-ui/index.html', {
    waitUntil: 'networkidle0',
    timeout: 60000
  });

  // Esperar a que Swagger UI termine de cargar
  await page.waitForSelector('.swagger-ui .information-container', { timeout: 10000 });
 
  // Expandir todos los nodos de la API
  await page.evaluate(() => {
    document.querySelectorAll('.opblock').forEach(el => {
      if (!el.classList.contains('is-open')) {
        el.querySelector('.opblock-summary').click();
      }
    });
  });

  // Esperar a que se complete la animación de expansión
  await page.waitForTimeout(2000);
 
  // Agregar estilos personalizados de encabezado y pie de página
  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;
      }
    `
  });

  // Generar PDF
  await page.pdf({
    path: path.join(outputDir, 'api-documentation.pdf'),
    format: 'A4',
    printBackground: true,
    displayHeaderFooter: true,
    headerTemplate: `<div class="page-header">Centro de documentación API</div>`,
    footerTemplate: `<div class="page-footer">
                       <span>Número de página<span class="pageNumber"></span> / <span class="totalPages"></span></span>
                       <span style="margin-left: 20px;">Fecha de generación: ${new Date().toLocaleDateString()}</span>
                     </div>`,
    margin: {
      top: '40px',
      bottom: '40px',
      left: '20px',
      right: '20px'
    }
  });

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

  // Cerrar el navegador
  await browser.close();
 
  console.log('Documento generado en el directorio:', outputDir);
})();

2. Instalar dependencias y ejecutar:

npm install puppeteer
node export-pdf.js

Resumen

Swagger UI es una potente herramienta de documentación de API. Con una configuración y uso adecuados, puede mejorar en gran medida la disponibilidad y la eficiencia de desarrollo de la API.

A través del contenido anterior, hemos aprendido los conceptos básicos de Swagger UI, métodos de integración, redacción de documentación, configuración personalizada, publicación de documentación, personalización de estilos y exportación de documentos.

Recuerde los siguientes puntos clave:

  1. Elija el método de integración de Swagger adecuado para la pila tecnológica del proyecto
  2. Diseñe y escriba cuidadosamente las anotaciones o comentarios de la documentación de la API
  3. Personalice la interfaz y los estilos de Swagger UI según sea necesario
  4. Agregue la identidad de marca para que la documentación sea más profesional
  5. Elija el método adecuado de publicación y exportación de documentación
  6. Siga las mejores prácticas para garantizar la precisión y seguridad de la documentación

Con un uso razonable de Swagger UI, puede proporcionar documentación profesional e interactiva para su API, haciéndola más fácil de entender y usar.

Otras extensiones