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
.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
return new SwaggerUiConfigParameters()
.withConfigUrl("/swagger-ui/custom.css");
}
Para SpringDoc OpenAPI:
Ejemplo
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
<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
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
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
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
<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
public class SwaggerUIConfig implements WebMvcConfigurer {
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController("/swagger-ui/").setViewName("swagger-ui");
registry.addRedirectViewController("/swagger-ui", "/swagger-ui/");
}
}