Swagger UI 主题样式修改
改主色、换 logo、调默认展开、去掉顶部栏，以及自定义 CSS 的注入方式。
Key Points优先用官方配置项（docExpansion、deepLinking、tryItOutEnabled）解决行为问题，视觉再用自定义 CSS 覆盖。
先看配置项
| Option | Effect |
|---|---|
| docExpansion | none / list / full — collapse tags by default |
| defaultModelsExpandDepth | -1 hides the Models section |
| tryItOutEnabled | Enable the try-it form on load |
| filter | Show the search box |
| deepLinking | URLs reflect the current operation |
| persistAuthorization | Keep the token across reloads |
JavaScript
SwaggerUIBundle({
url: "./openapi.yaml",
dom_id: "#swagger-ui",
docExpansion: "list",
defaultModelsExpandDepth: -1,
tryItOutEnabled: true,
filter: true,
deepLinking: true,
persistAuthorization: true,
});覆盖样式
Swagger UI's class names are stable enough to override directly. Use !important sparingly or upgrades will fight you.
CSS
/* 主色 */
.swagger-ui .topbar { background-color: #0f172a; }
.swagger-ui .info .title { color: #0f172a; }
.swagger-ui .opblock.opblock-get { border-color: #2563eb; }
.swagger-ui .opblock.opblock-get .opblock-summary-method { background: #2563eb; }
/* 字体 */
.swagger-ui { font-family: "Inter", system-ui, sans-serif; }
/* 隐藏顶部栏 */
.swagger-ui .topbar { display: none; }HTML
<link rel="stylesheet" href="./custom.css">换 logo
CSS
.swagger-ui .topbar-wrapper .link svg { display: none; }
.swagger-ui .topbar-wrapper .link {
background: url("./logo.svg") no-repeat center / contain;
width: 140px; height: 36px;
}深色模式
CSS
@media (prefers-color-scheme: dark) {
body { background: #0b1220; }
.swagger-ui { filter: invert(0.92) hue-rotate(180deg); }
.swagger-ui img, .swagger-ui .microlight { filter: invert(1) hue-rotate(180deg); }
}filter: invert() is the cheapest dark mode, but it flips images and code highlighting too — invert those back. For finer control, override the CSS variables instead.Spring Boot 里注入
Java
@Configuration
public class SwaggerUiConfig {
@Bean
public SwaggerUiConfigProperties.Css css() {
SwaggerUiConfigProperties.Css c = new SwaggerUiConfigProperties.Css();
c.setUrl("/custom.css");
return c;
}
}先看配置项
| 配置项 | 作用 |
|---|---|
| docExpansion | none / list / full —— 默认折叠程度 |
| defaultModelsExpandDepth | -1 隐藏 Models 区块 |
| tryItOutEnabled | 载入即开启调试表单 |
| filter | 显示搜索框 |
| deepLinking | URL 随当前接口变化 |
| persistAuthorization | 刷新后保留 token |
JavaScript
SwaggerUIBundle({
url: "./openapi.yaml",
dom_id: "#swagger-ui",
docExpansion: "list",
defaultModelsExpandDepth: -1,
tryItOutEnabled: true,
filter: true,
deepLinking: true,
persistAuthorization: true,
});覆盖样式
Swagger UI 的类名是稳定的，直接覆盖即可。用 !important 的地方越少越好，否则升级后容易打架。
CSS
/* 主色 */
.swagger-ui .topbar { background-color: #0f172a; }
.swagger-ui .info .title { color: #0f172a; }
.swagger-ui .opblock.opblock-get { border-color: #2563eb; }
.swagger-ui .opblock.opblock-get .opblock-summary-method { background: #2563eb; }
/* 字体 */
.swagger-ui { font-family: "Inter", system-ui, sans-serif; }
/* 隐藏顶部栏 */
.swagger-ui .topbar { display: none; }HTML
<link rel="stylesheet" href="./custom.css">换 logo
CSS
.swagger-ui .topbar-wrapper .link svg { display: none; }
.swagger-ui .topbar-wrapper .link {
background: url("./logo.svg") no-repeat center / contain;
width: 140px; height: 36px;
}深色模式
CSS
@media (prefers-color-scheme: dark) {
body { background: #0b1220; }
.swagger-ui { filter: invert(0.92) hue-rotate(180deg); }
.swagger-ui img, .swagger-ui .microlight { filter: invert(1) hue-rotate(180deg); }
}filter: invert() 是最省事的深色方案，但会把图片和代码高亮一起反色，所以要对 img 和 .microlight 再反回来。追求精细就自己写变量。Spring Boot 里注入
Java
@Configuration
public class SwaggerUiConfig {
@Bean
public SwaggerUiConfigProperties.Css css() {
SwaggerUiConfigProperties.Css c = new SwaggerUiConfigProperties.Css();
c.setUrl("/custom.css");
return c;
}
}