自定义 Linux 中 Swagger UI 的样式

Swagger UI 提供了多种方式来自定义其外观和样式。以下是几种主要的方法：

方法一：通过 Swagger UI 配置参数

Swagger UI 本身提供了一些配置选项来自定义基本样式：

const ui = SwaggerUIBundle({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout",
  // 自定义配置
  validatorUrl: null,
  docExpansion: 'none',
  defaultModelsExpandDepth: -1,
  displayRequestDuration: true,
  filter: true
})

方法二：覆盖 CSS 样式

1. 首先找到 Swagger UI 的 CSS 文件位置（通常在 dist/swagger-ui.css）

2. 创建你自己的 CSS 文件并覆盖默认样式：

/* 自定义主题色 */
.swagger-ui .topbar {
  background-color: #2c3e50;
}

/* 修改标题样式 */
.swagger-ui .info .title {
  color: #2c3e50;
  font-size: 24px;
}

/* 修改操作按钮颜色 */
.swagger-ui .btn {
  background-color: #3498db;
}

/* 隐藏模型部分 */
.swagger-ui .models {
  display: none;
}

3. 在你的 HTML 文件中引入自定义 CSS（确保在 Swagger UI 的 CSS 之后引入）：

<link rel="stylesheet" href="swagger-ui.css">
<link rel="stylesheet" href="custom.css">

方法三：使用主题插件

Swagger UI 支持主题插件，你可以使用现有的主题或创建自己的主题：

1. 安装主题插件，例如 swagger-ui-themes：

npm install swagger-ui-themes

2. 在代码中应用主题：

import { SwaggerUIStandalonePreset } from 'swagger-ui-dist/swagger-ui-standalone-preset'
import { themes } from 'swagger-ui-themes'

const ui = SwaggerUIBundle({
  url: "https://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout",
  theme: themes.get('material') // 应用主题
})

方法四：完全自定义构建

对于更深入的自定义，你可以 fork Swagger UI 项目并修改源代码：

1. 克隆 Swagger UI 仓库：

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

2. 安装依赖：

npm install

3. 修改 src/style/_variables.scss 中的 Sass 变量

4. 构建自定义版本：

npm run build

常见自定义场景

1. 更改颜色方案：

   :root {
    --swagger-ui-color-primary: #4285f4;
    --swagger-ui-color-secondary: #34a853;
   }
   

2. 隐藏某些部分：

   /* 隐藏模型部分 */
   .swagger-ui .models {
    display: none;
   }
   
   /* 隐藏顶部栏 */
   .swagger-ui .topbar {
    display: none;
   }
   

3. 修改字体：

   .swagger-ui {
    font-family: 'Roboto', sans-serif;
   }
   

4. 调整布局：

   /* 使操作面板更宽 */
   .swagger-ui .opblock-section {
    width: 70%;
   }
   

注意事项

1. 自定义样式时，确保你的 CSS 选择器具有足够的特异性来覆盖默认样式
2. 在更新 Swagger UI 版本时，检查你的自定义样式是否仍然有效
3. 考虑使用 CSS 变量以便于主题切换和维护
4. 对于生产环境，建议将自定义 CSS 最小化以减少加载时间

通过以上方法，你可以完全控制 Swagger UI 的外观，使其与你的应用程序或品牌风格保持一致。