Swagger于Linux怎样定制样式

Swagger于Linux环境下的样式定制方法

1. 准备工作：获取Swagger UI资源

在Linux系统上定制Swagger样式前，需先获取Swagger UI的资源文件。常见方式有两种：

• 通过npm安装：使用npm install swagger-ui-dist（或yarn add swagger-ui-dist）下载Swagger UI的预编译资源，资源会存放在项目的node_modules/swagger-ui-dist目录下。
• 通过Docker运行：拉取Swagger UI的Docker镜像并启动容器，命令为docker pull swaggerapi/swagger-ui:v4.15.5（版本号可根据需求调整），然后运行docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5，容器会暴露Swagger UI的Web界面（默认地址为http://< 服务器IP> :38081/swagger-ui/index.html）。

2. CSS覆盖：最常用的样式定制方式

通过编写自定义CSS文件覆盖Swagger UI的默认样式，是最灵活且不影响源码的方法。

• 创建自定义CSS文件：在项目目录下新建custom.css（或其他名称），编写样式规则。例如：

  /* 修改顶部导航栏背景色 */
  .swagger-ui .topbar {
      
    background-color: #007bff !important;
  
  }
  
  /* 修改API标题颜色和字体大小 */
  .swagger-ui .info .title {
      
    color: #333 !important;
      
    font-size: 24px !important;
  
  }
  
  /* 修改文档背景色 */
  .swagger-ui {
      
    background-color: #f8f9fa !important;
  
  }
      
  

  上述示例中，!important用于提升样式优先级，确保覆盖默认样式。
• 引入自定义CSS文件：
  • 若使用npm安装的Swagger UI，需在HTML文件中引入自定义CSS（确保在Swagger UI的CSS之后加载）。例如：

    <
        !DOCTYPE html>
        
    <
        html>
        
    <
        head>
        
      <
        link rel="stylesheet" href="node_modules/swagger-ui-dist/swagger-ui.css">
        
      <
        link rel="stylesheet" href="./custom.css">
         <
        !-- 自定义CSS -->
        
    <
        /head>
        
    <
        body>
        
      <
        div id="swagger-ui">
        <
        /div>
        
      <
        script src="node_modules/swagger-ui-dist/swagger-ui-bundle.js">
        <
        /script>
        
      <
        script src="node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js">
        <
        /script>
        
      <
        script>
    
        window.onload = function() {
    
          SwaggerUIBundle({
    
            url: "your-api-spec.json",
            dom_id: '#swagger-ui',
            presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset]
          }
        );
    
        }
        ;
        
      <
        /script>
        
    <
        /body>
        
    <
        /html>
        
    

  • 若使用Docker运行的Swagger UI，需将自定义CSS文件挂载到容器内的dist目录（默认路径为/usr/local/src/swagger-ui/dist），或在index.html中直接引入自定义CSS的路径。

3. 第三方主题库：快速应用预设样式

若不想手动编写CSS，可使用第三方主题库简化流程。例如：

• think-swagger-ui-vuele：基于Vue.js的Swagger UI实现，支持自定义主题。操作步骤如下：
  1. 克隆项目仓库：git clone https://github.com/chfree/think-swagger-ui-vuele.git；
  2. 进入项目目录并安装依赖：cd think-swagger-ui-vuele & & npm install；
  3. 运行开发服务器：npm run dev；
  4. 修改项目中的主题配置文件（如src/config/theme.js），调整颜色、字体等参数；
  5. 重新编译并部署项目。

4. 直接修改Swagger UI源码：深度定制

若需要彻底修改UI结构或功能，可直接修改Swagger UI的源码。步骤如下：

• 克隆Swagger UI仓库：git clone https://github.com/swagger-api/swagger-ui.git；
• 修改源码：进入仓库目录，修改src/core或src/style目录下的源码文件（如topbar.js、topbar.css）；
• 编译并部署：运行npm install安装依赖，再执行npm run build编译项目，将生成的dist目录部署到Linux服务器上。

5. 使用配置文件或插件：简化定制流程

部分工具或框架提供了配置文件或插件，简化Swagger样式的定制。例如：

• swagger-ui-theme插件：通过命令行工具快速生成主题。安装插件：npm install swagger-ui-theme，然后运行swagger-ui-theme --theme-id my-custom-theme，按照提示配置主题参数（如主色调、字体等）。

注意事项

• 优先级问题：自定义CSS需使用!important提升优先级，避免被默认样式覆盖；
• 路径问题：确保自定义CSS文件的路径在HTML中正确引入（尤其是Docker环境下需挂载路径）；
• 版本兼容性：不同版本的Swagger UI可能有不同的CSS类名，建议参考对应版本的文档或源码。

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