Ubuntu如何自定义Swagger主题 - 问答

Ubuntu自定义Swagger主题的常见方法

1. 使用Docker快速部署并修改配置

通过Docker运行Swagger UI容器，便于后续修改配置。首先安装Docker并拉取镜像：

sudo apt update && sudo apt install docker.io
docker pull swaggerapi/swagger-ui:v4.15.5

运行容器并映射端口：

docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5

进入容器内的Swagger UI目录：

docker exec -it <容器ID> /bin/bash
cd /usr/local/src/swagger-ui/dist

修改index.html中的theme属性（如切换为dark主题），或通过浏览器直接调整页面主题设置。

2. 修改样式文件（适用于Knife4j等项目）

若使用Knife4j等基于Vue/React的Swagger封装项目，可直接修改样式源文件：

找到项目中的src/style/knife4j.less（或类似路径的LESS/SASS文件），修改颜色、布局等样式规则（如修改顶部栏背景色）：
```
.swagger-ui .topbar {
  background-color: #007bff !important;
}
.swagger-ui .info .title {
  color: #333 !important;
}
```
保存后运行npm run build重新打包，将生成的dist文件夹替换原依赖。

3. CSS覆盖法（通用且灵活）

通过自定义CSS文件覆盖Swagger UI默认样式，适用于所有基于Web的Swagger部署：

在项目根目录创建custom.css文件，添加自定义样式（如修改标题颜色、背景色）：

.swagger-ui .topbar {
  background-color: #28a745;
}
.swagger-ui .info .description {
  color: #6c757d;
}

在Swagger UI的HTML入口文件（如index.html）中，确保custom.css在Swagger UI默认CSS之后引入：

<link rel="stylesheet" type="text/css" href="/path/to/swagger-ui.css">
<link rel="stylesheet" type="text/css" href="/path/to/custom.css">

启动服务后，浏览器会自动加载自定义样式。

4. 前端框架集成定制（Vue/React示例）

若项目使用前端框架，可通过框架特性深度定制Swagger UI：

Vue项目：修改docs.html文件，解析Swagger JSON数据并渲染自定义组件（如替换默认的侧边栏导航为树形结构）。

React项目：使用swagger-ui-react库，通过theme属性传递自定义主题对象（如设置主色调、字体大小）：

import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

const App = () => (
  <SwaggerUI
    url="http://localhost:8080/api-docs"
    theme={{
      colors: {
        primary: '#ff6b6b',
        secondary: '#4ecdc4',
      },
      fontFamily: 'Arial, sans-serif',
    }}
  />
);

运行项目后，Swagger UI将应用框架定制的样式。

5. 第三方主题或插件扩展

利用现成的第三方主题库简化定制流程：

think-swagger-ui-vuele（Vue项目）：克隆仓库后安装依赖并运行，通过修改配置文件调整主题：

git clone https://github.com/chfree/think-swagger-ui-vuele.git
cd think-swagger-ui-vuele
npm install
npm run dev

swagger-ui-bootstrap（Java项目）：集成Bootstrap框架，通过Bootstrap的CSS类快速定制Swagger UI的按钮、表单样式。

6. 直接修改Swagger UI源代码（高级用户）

若需要彻底定制，可克隆Swagger UI官方仓库，修改源代码后重新编译：

克隆仓库：

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui

修改源代码（如调整src/core/components/topbar.js中的顶部栏样式逻辑），然后运行以下命令编译：
```
npm install
npm run build
```
将编译后的dist文件夹部署到服务器，覆盖原有文件。

以上方法可根据项目需求选择，优先推荐CSS覆盖法（灵活且不影响源码）或Docker配置法（快速部署）。若使用前端框架，框架集成定制能实现更深度的个性化需求。

0 赞

0 踩