Swagger UI Theme-Styling

Swagger UI bietet mehrere Möglichkeiten, den Stil der Benutzeroberfläche anzupassen, sodass die Dokumentation besser zur Corporate- oder Produktmarkenidentität passt.

In einem Spring Boot-Projekt können Sie eine benutzerdefinierte CSS-Datei erstellen und Swagger UI so konfigurieren, dass sie diese verwendet:

Erstellen Sie eine benutzerdefinierte CSS-Datei, zum Beispiel src/main/resources/static/swagger-ui/custom.css:

Beispiel

/* Farbe der oberen Leiste ändern */
.swagger-ui .topbar {
  background-color: #1e88e5;
}

/* Linkfarben ändern */
.swagger-ui .info a {
  color: #1e88e5;
}

/* Button-Stile ändern */
.swagger-ui .btn.execute {
  background-color: #4576A6;
  color: white;
}

/* Beschriftungen der Request-Methode ändern */
.swagger-ui .opblock-get .opblock-summary-method {
  background-color: #29b6f6;
}

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

/* Einklappbare Panels anpassen */
.swagger-ui .opblock {
  border-radius: 4px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.12);
}

/* Benutzerdefinierte Schriftarten */
.swagger-ui {
  font-family: 'Roboto', sans-serif;
}

Verweisen Sie in der Swagger-Konfiguration auf das benutzerdefinierte CSS:

Beispiel

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

Für SpringDoc OpenAPI:

Beispiel

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

Verwendung von Theme-Plugins

Für komplexere Theme-Anpassungen können Sie Swagger UI Theme-Plugins verwenden.

Um das Theme-Plugin zu installieren (erwägen Sie in China, andere CDNs zu verwenden oder es lokal zu hosten):

Beispiel

<!-- In die HTML-Datei einfügen -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-material.css">

Für Express-Projekte:

Beispiel

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

Häufig verwendete Themes sind:

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

Logo und Markenidentität hinzufügen

Ein Logo in Spring Boot hinzufügen

Beispiel

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("API-Schnittstellendokumentation")
                    .version("1.0.0")
                    .description("Detaillierte Beschreibung der API-Schnittstelle")
                    .contact(new Contact()
                            .name("Entwicklungsteam")
                            .email("[email protected]")
                            .url("https://example.com"))
                    // x-logo-Erweiterung hinzufügen
                    .addExtension("x-logo", Map.of(
                            "url", "/images/logo.png",
                            "backgroundColor", "#FFFFFF",
                            "altText", "Firmenlogo"
                    )));
}

Ein Logo in Express hinzufügen

Beispiel

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

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

Benutzerdefinierte Vorlagen verwenden

Für eine tiefergehende Anpassung können Sie benutzerdefinierte Swagger-UI-Vorlagen verwenden.

1. Erstellen Sie eine benutzerdefinierte Vorlagendateisrc/main/resources/templates/swagger-ui.html:

Beispiel

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>API-Dokumentationszentrum</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;
        }
        .Firmen-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="Firmenlogo" class="company-logo">
        <h1>API-Dokumentationszentrum</h1>
    </div>

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

    <div class="footer">
        <p>© 2025Firmenname. Alle Rechte vorbehalten.</p>
        <p>Wenn Sie Fragen haben, kontaktieren Sie bitte: <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. Konfigurieren und verwenden Sie die benutzerdefinierte Vorlage im Spring-Boot-Projekt:

Beispiel

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/");
    }
}
Andere Erweiterungen