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配置法（快速部署）。若使用前端框架，框架集成定制能实现更深度的个性化需求。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！