Swagger UI Theme Styling

Swagger UI provides multiple ways to customize the interface style, making the documentation more aligned with corporate or product brand identity.

In a Spring Boot project, you can create a custom CSS file and configure Swagger UI to use it:

Create a custom CSS file, for example src/main/resources/static/swagger-ui/custom.css:

Example

/* Modify the top bar color */
.swagger-ui .topbar {
  background-color: #1e88e5;
}

/* Modify link colors */
.swagger-ui .info a {
  color: #1e88e5;
}

/* Modify button styles */
.swagger-ui .btn.execute {
  background-color: #4576A6;
  color: white;
}

/* Modify request method labels */
.swagger-ui .opblock-get .opblock-summary-method {
  background-color: #29b6f6;
}

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

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

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

Reference the custom CSS in the Swagger configuration:

Example

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

For SpringDoc OpenAPI:

Example

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

Using Theme Plugins

For more complex theme customization, you can use Swagger UI theme plugins.

To install the theme plugin (in China, consider using other CDNs or hosting it locally):

Example

<!-- Add in the HTML file -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.0/themes/3.x/theme-material.css">

For Express projects:

Example

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

Common themes include:

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

Adding Logo and Brand Identity

Adding a Logo in Spring Boot

Example

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("API Interface Documentation")
                    .version("1.0.0")
                    .description("API Interface Detailed Description")
                    .contact(new Contact()
                            .name("Development Team")
                            .email("team@example.com")
                            .url("https://example.com"))
                    // Add the x-logo extension
                    .addExtension("x-logo", Map.of(
                            "url", "/images/logo.png",
                            "backgroundColor", "#FFFFFF",
                            "altText", "Company Logo"
                    )));
}

Adding a Logo in Express

Example

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

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

Using Custom Templates

For deeper-level customization, you can use custom Swagger UI templates.

1. Create a custom template filesrc/main/resources/templates/swagger-ui.html:

Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>API Documentation Center</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="Company Logo" class="company-logo">
        <h1>API Documentation Center</h1>
    </div>

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

    <div class="footer">
        <p>© 2025Company Name. All rights reserved.</p>
        <p>If you have any questions, please contact: <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. Configure and use the custom template in the Spring Boot project:

Example

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/");
    }
}
Other Extensions