Swagger UI 主题样式修改

Swagger UI 提供了多种方式来自定义界面样式，让文档更符合企业或产品品牌形象。

在 Spring Boot 项目中，可以创建自定义 CSS 文件并配置 Swagger UI 使用:

创建自定义 CSS 文件，例如 src/main/resources/static/swagger-ui/custom.css:

实例

/* 修改顶栏颜色 */
.swagger-ui .topbar {
  background-color: #1e88e5;
}

/* 修改链接颜色 */
.swagger-ui .info a {
  color: #1e88e5;
}

/* 修改按钮样式 */
.swagger-ui .btn.execute {
  background-color: #43a047;
  color: white;
}

/* 修改请求方法标签 */
.swagger-ui .opblock-get .opblock-summary-method {
  background-color: #29b6f6;
}

.swagger-ui .opblock-post .opblock-summary-method {
  background-color: #66bb6a;
}

/* 修改折叠面板 */
.swagger-ui .opblock {
  border-radius: 4px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.12);
}

/* 自定义字体 */
.swagger-ui {
  font-family: 'Roboto', sans-serif;
}

在 Swagger 配置中引用自定义 CSS:

实例

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

对于 SpringDoc OpenAPI:

实例

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

使用主题插件

对于更复杂的主题定制，可以使用 Swagger UI 主题插件。

安装主题插件(国内可以考虑其他 CDN 或者放到本地):

实例

<!-- 在 HTML 文件中添加 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.0/themes/3.x/theme-material.css">

对于 Express 项目:

实例

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

常见的主题包括:

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

添加 Logo 和品牌标识

Spring Boot 中添加 Logo

实例

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("API 接口文档")
                    .version("1.0.0")
                    .description("API 接口详细描述")
                    .contact(new Contact()
                            .name("开发团队")
                            .email("team@example.com")
                            .url("https://example.com"))
                    // 添加 x-logo 扩展
                    .addExtension("x-logo", Map.of(
                            "url", "/images/logo.png",
                            "backgroundColor", "#FFFFFF",
                            "altText", "公司 Logo"
                    )));
}

Express 中添加 Logo

实例

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

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

使用自定义模板

对于更深层次的定制，可以使用自定义 Swagger UI 模板。

1. 创建自定义模板文件 src/main/resources/templates/swagger-ui.html:

实例

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>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" class="company-logo">
        <h1>API 文档中心</h1>
    </div>

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

    <div class="footer">
        <p>© 2025 公司名称. 版权所有.</p>
        <p>如有问题，请联系: <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. 在 Spring Boot 项目中配置使用自定义模板:

实例

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