Modificación del estilo del tema de Swagger UI

Swagger UI ofrece múltiples formas de personalizar el estilo de la interfaz, para que la documentación se ajuste mejor a la imagen de marca de la empresa o del producto.

En un proyecto Spring Boot, puedes crear un archivo CSS personalizado y configurar Swagger UI para usarlo:

Crear un archivo CSS personalizado, por ejemplo src/main/resources/static/swagger-ui/custom.css:

Ejemplo

/* Modificar el color de la barra superior */
.swagger-ui .topbar {
  background-color: #1e88e5;
}

/* Modificar el color de los enlaces */
.swagger-ui .info a {
  color: #1e88e5;
}

/* Modificar el estilo de los botones */
.swagger-ui .btn.execute {
  background-color: #4576A6;
  color: white;
}

/* Modificar las etiquetas de los métodos de solicitud */
.swagger-ui .opblock-get .opblock-summary-method {
  background-color: #29b6f6;
}

.swagger-ui .opblock-post .opblock-summary-method {
  background-color: #6690BB;
}

/* Modificar los paneles plegables */
.swagger-ui .opblock {
  border-radius: 4px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.12);
}

/* Personalizar la fuente */
.swagger-ui {
  font-family: 'Roboto', sans-serif;
}

Referenciar el CSS personalizado en la configuración de Swagger:

Ejemplo

public SwaggerUiConfigParameters swaggerUiConfigParameters() {
    return new SwaggerUiConfigParameters()
            .withConfigUrl("/swagger-ui/custom.css");
}

Para SpringDoc OpenAPI:

Ejemplo

# application.yml
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    config-url: /swagger-ui/custom.css

Uso de complementos de temas

Para personalizaciones de temas más complejas, se pueden utilizar los complementos de temas de Swagger UI.

Instalar el complemento de temas (en China se puede considerar usar otros CDN o colocarlo localmente):

Ejemplo

<!-- Añadir en el archivo HTML -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.0/themes/3.x/theme-material.css">

Para proyectos Express:

Ejemplo

javascriptconst express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const options = {
  customCssUrl: 'https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.0/themes/3.x/theme-material.css'
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Los temas comunes incluyen:

  • Material: theme-material.css
  • Monokai: theme-monokai.css
  • Muted: theme-muted.css
  • Flattop: theme-flattop.css
  • Feeling Blue: theme-feeling-blue.css

Agregar Logo y marca

Agregar Logo en Spring Boot

Ejemplo

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title(Documentación de la API)
                    .version("1.0.0")
                    .description(Descripción detallada de la API)
                    .contact(new Contact()
                            .name(Equipo de desarrollo)
                            .email("team@example.com")
                            .url("https://example.com"))
                    // Agregar la extensión x-logo
                    .addExtension("x-logo", Map.of(
                            "url", "/images/logo.png",
                            "backgroundColor", "#FFFFFF",
                            "altText", Logo de la empresa
                    )));
}

Agregar Logo en Express

Ejemplo

const swaggerOptions = {
  swaggerOptions: {
    plugins: [{
      statePlugins: {
        spec: {
          wrapSelectors: {
            info: (ori) => (...args) => {
              return {
                ...ori(...args),
                'x-logo': {
                  url: '/images/logo.png',
                  backgroundColor: '#FFFFFF',
                  altText: 'Logo de la empresa'
                }
              };
            }
          }
        }
      }
    }]
  }
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs, swaggerOptions));

Usar plantillas personalizadas

Para una personalización más profunda, se pueden usar plantillas personalizadas de Swagger UI.

1. Crear un archivo de plantilla personalizadosrc/main/resources/templates/swagger-ui.html:

Ejemplo

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Centro de documentación de API</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.5.0/swagger-ui.css">
    <link rel="stylesheet" href="/swagger-ui/custom.css">
    <link rel="icon" type="image/png" href="/images/favicon.png" sizes="32x32">
    <style>
        .company-header {
            padding: 20px;
            background-color: #f8f8f8;
            text-align: center;
            border-bottom: 1px solid #ddd;
        }
        .company-logo {
            max-height: 50px;
        }
        .footer {
            text-align: center;
            padding: 20px;
            color: #666;
            font-size: 12px;
            border-top: 1px solid #ddd;
            margin-top: 20px;
        }
    </style>
</head>
<body>
    <div class="company-header">
        <img src="/images/logo.png" alt=Logo de la empresa class="company-logo">
        <h1>Centro de documentación de API</h1>
    </div>

    <div id="swagger-ui"></div>

    <div class="footer">
        <p>© 2025Nombre de la empresa. Todos los derechos reservados.</p>
        <p>Si tiene alguna pregunta, póngase en contacto con: <a href="mailto:api@example.com">api@example.com</a></p>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.5.0/swagger-ui-bundle.js"></script>
    <script>
        window.onload = function() {
            const ui = SwaggerUIBundle({
                url: '/v3/api-docs',
                dom_id: '#swagger-ui',
                deepLinking: true,
                presets: [
                    SwaggerUIBundle.presets.apis,
                    SwaggerUIBundle.SwaggerUIStandalonePreset
                ],
                layout: 'BaseLayout',
                docExpansion: 'none',
                tagsSorter: 'alpha',
                operationsSorter: 'alpha'
            });
            window.ui = ui;
        }
    </script>
</body>
</html>

2. Configurar el uso de plantillas personalizadas en un proyecto Spring Boot:

Ejemplo

java@Configuration
public class SwaggerUIConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/swagger-ui/").setViewName("swagger-ui");
        registry.addRedirectViewController("/swagger-ui", "/swagger-ui/");
    }
}
Otras extensiones