Personnalisation du thème de Swagger UI

Swagger UI offre plusieurs façons de personnaliser le style de l'interface, ce qui permet à la documentation de mieux correspondre à l'identité de marque de l'entreprise ou du produit.

Dans un projet Spring Boot, vous pouvez créer un fichier CSS personnalisé et configurer Swagger UI pour l'utiliser :

Créez un fichier CSS personnalisé, par exemple src/main/resources/static/swagger-ui/custom.css :

Exemple

/* Modifier la couleur de la barre supérieure */
.swagger-ui .topbar {
  background-color: #1e88e5;
}

/* Modifier les couleurs des liens */
.swagger-ui .info a {
  color: #1e88e5;
}

/* Modifier les styles des boutons */
.swagger-ui .btn.execute {
  background-color: #4576A6;
  color: white;
}

/* Modifier les libellés des méthodes de requête */
.swagger-ui .opblock-get .opblock-summary-method {
  background-color: #29b6f6;
}

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

/* Modifier les panneaux pliables */
.swagger-ui .opblock {
  border-radius: 4px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.12);
}

/* Polices personnalisées */
.swagger-ui {
  font-family: 'Roboto', sans-serif;
}

Référencez le CSS personnalisé dans la configuration Swagger :

Exemple

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

Pour SpringDoc OpenAPI :

Exemple

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

Utilisation des plugins de thème

Pour une personnalisation de thème plus complexe, vous pouvez utiliser les plugins de thème Swagger UI.

Pour installer le plugin de thème (en Chine, envisagez d'utiliser d'autres CDN ou de l'héberger localement) :

Exemple

<!-- Ajouter dans le fichier HTML -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-material.css">

Pour les projets Express :

Exemple

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

const options = {
  customCssUrl: 'https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-material.css'
};

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

Les thèmes courants incluent :

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

Ajout d'un logo et de l'identité de marque

Ajout d'un logo dans Spring Boot

Exemple

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("Documentation de l'interface API")
                    .version("1.0.0")
                    .description("Description détaillée de l'interface API")
                    .contact(new Contact()
                            .name("Équipe de développement")
                            .email("[email protected]")
                            .url("https://example.com"))
                    // Ajouter l'extension x-logo
                    .addExtension("x-logo", Map.of(
                            "url", "/images/logo.png",
                            "backgroundColor", "#FFFFFF",
                            "altText", "Logo de l'entreprise"
                    )));
}

Ajouter un logo dans Express

Exemple

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

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

Utilisation de modèles personnalisés

Pour une personnalisation plus approfondie, vous pouvez utiliser des modèles Swagger UI personnalisés.

1. Créez un fichier de modèle personnalisésrc/main/resources/templates/swagger-ui.html:

Exemple

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Centre de documentation de l'API</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/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;
        }
        .logo de l'-entreprise {
            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 l'entreprise" class="company-logo">
        <h1>Centre de documentation de l'API</h1>
    </div>

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

    <div class="footer">
        <p>© 2025Nom de l'entreprise. Tous droits réservés.</p>
        <p>Si vous avez des questions, veuillez contacter: <a href="mailto:[email protected]">api@example.com</a></p>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/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. Configurer et utiliser le modèle personnalisé dans le projet Spring Boot :

Exemple

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/");
    }
}
Autres extensions