Springdoc OpenAPI UI第三方皮肤如何自定义样式和布局？

Question

如何在Springdoc OpenAPI UI中自定义第三方皮肤的样式和布局？ 默认情况下，Springdoc OpenAPI使用Swagger UI作为文档展示工具，但有时我们需要根据项目需求调整UI样式或布局。要实现这一点，可以通过覆盖Swagger UI的CSS样式或修改其配置文件来完成。首先，引入自定义CSS文件，覆盖原有样式。例如，调整字体、背景色或按钮样式。其次，通过设置springdoc.ui.configUrl属性，加载自定义的Swagger配置文件，从而更改布局（如操作分组、主题等）。最后，若需更深度定制，可引入第三方Swagger UI皮肤库（如swagger-ui-themes），并结合NPM或CDN方式集成到项目中。如何优雅地实现这些自定义改动，同时确保兼容性和可维护性？

Answer 1

1. 理解Springdoc OpenAPI UI的默认样式与布局

在开始自定义Springdoc OpenAPI UI之前，了解其默认行为至关重要。Springdoc OpenAPI使用Swagger UI作为文档展示工具，默认提供了一套标准化的UI样式和布局。这些样式主要由Swagger UI的核心CSS文件控制。

• 字体： 默认为Roboto，适合现代界面设计。
• 颜色： 主题以蓝色为主色调，搭配白色背景。
• 按钮样式： 圆角矩形，悬停时有轻微阴影效果。

要实现自定义样式，首先需要明确目标：是简单的样式覆盖，还是更深层次的布局调整？这将决定后续的技术选型。

2. 引入自定义CSS文件

通过引入自定义CSS文件，可以轻松覆盖Swagger UI的默认样式。以下是一个基本步骤示例：

1. 创建一个名为custom.css的文件，放置在src/main/resources/static/目录下。
2. 在application.properties中添加如下配置：

springdoc.swagger-ui.css-url=/static/custom.css
    

例如，在custom.css中定义：

body {
    background-color: #f5f5f5;
    font-family: 'Arial', sans-serif;
}
button {
    background-color: #007bff;
    color: white;
}
    

这种简单的方式适用于大多数项目需求，但可能不够灵活，尤其是在复杂定制场景下。

3. 修改Swagger UI配置文件

若需更深层次的定制，比如调整操作分组、启用深色模式等，可以通过修改Swagger UI配置文件来实现。

属性	说明	示例值
deepLinking	是否支持URL深度链接	true
layout	UI布局模式（如StandaloneLayout）	StandaloneLayout
theme	主题颜色方案	swagger或dark

通过设置springdoc.ui.configUrl指向自定义配置文件：

springdoc.ui.configUrl=/swagger-config.json
    

4. 使用第三方皮肤库

对于更高级的需求，可引入第三方皮肤库，如swagger-ui-themes。以下是集成步骤：

1. 通过NPM安装：npm install swagger-ui-themes。
2. 在前端代码中引用：

import 'swagger-ui-themes/themes/dark.min.css';
    

或者通过CDN直接加载：

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.1/themes/dark.min.css">
    

这种方式不仅简化了开发流程，还确保了兼容性和可维护性。

5. 自定义改动的优雅实现

为了确保改动既美观又实用，建议遵循以下原则：

• 模块化： 将样式和配置分离，便于维护。
• 版本控制： 使用Git记录每次更改，方便回滚。
• 测试驱动： 在不同浏览器和设备上测试效果。

以下是一个简单的流程图，描述了从需求到实现的过程：

graph TD;
            A[需求分析] --> B[选择方案];
            B --> C{引入CSS};
            B --> D{修改配置};
            B --> E{使用第三方库};
            C --> F[应用样式];
            D --> G[验证效果];
            E --> H[集成库];