在 Debian 上定制 Swagger UI 的可行路径
- 使用 Node.js + swagger-ui-express 托管并深度定制（适合已有后端服务）
- 使用 官方 swagger-ui 静态包 + Nginx/Apache（适合纯静态托管、反向代理）
- 使用 Docker 运行 swaggerapi/swagger-ui（适合快速部署与隔离环境）
- 进阶：基于 swagger-ui 源码主题与插件 做品牌化深度改造（适合需要重写布局/交互的场景）
方案一 使用 Node.js 与 swagger-ui-express 托管并定制
- 安装运行时与依赖
- 安装 Node.js 与 npm：sudo apt update && sudo apt install -y nodejs npm
- 全局安装 swagger-ui-express：sudo npm install -g swagger-ui-express
- 若使用 YAML：npm install -D yamljs
- 准备规范文件
- 放置 swagger.yaml 或 swagger.json（示例见下）
- 启动服务与基础定制
- 新建 server.js（或 app.js），示例：
- const express = require(‘express’);
const swaggerUi = require(‘swagger-ui-express’);
const YAML = require(‘yamljs’);
const swaggerDocument = YAML.load(‘./swagger.yaml’);
const app = express();
app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
deepLinking: true,
presets: [swaggerUi.presets.apis, swaggerUi.presets.topbar],
layout: ‘StandaloneLayout’
}));
const port = process.env.PORT || 3000;
app.listen(port, () => console.log(
Swagger UI: http://localhost:${port}/api-docs));
- 运行：node server.js
- 常用定制要点
- 自定义 CSS/JS：将文件放入 public 并通过配置项引入
- app.use(‘/custom’, express.static(path.join(__dirname, ‘public’)));
- 在 swaggerUi.setup 中增加：customCssUrl: ‘/custom/custom.css’, customJsUrl: ‘/custom/custom.js’
- 请求/响应拦截：使用 requestInterceptor / responseInterceptor 统一注入头、脱敏或调试信息
- 安全配置：在 swaggerDocument.components.securitySchemes 定义 API Key / OAuth2 等，并在需要保护的路径上声明 security 要求
- 快速 YAML 示例（供测试）
- swagger: ‘2.0’
info:
title: Sample API
description: 示例 API
version: ‘1.0.0’
paths:
/ping:
get:
summary: 健康检查
responses:
‘200’:
description: OK
- 访问：http://localhost:3000/api-docs
方案二 使用官方静态包与 Nginx 或 Docker 部署
- 静态包 + Nginx/Apache
- 下载 swagger-ui-dist 静态文件（或通过 npm 安装到本地 node_modules/swagger-ui-dist）
- 将 index.html 中的 url 指向你的 swagger.yaml/swagger.json
- 用 Nginx/Apache 托管静态文件，并配置反向代理或别名，便于统一域名与鉴权
- Docker 快速部署
- 拉取并运行：
- docker pull swaggerapi/swagger-ui
- docker run -p 8080:8080 -e SWAGGER_JSON=/spec/swagger.yaml -v /path/to/spec:/spec swaggerapi/swagger-ui
- 访问：http://服务器IP:8080
- 适用场景
- 无后端侵入、静态站点托管、与现有网关/鉴权体系解耦
方案三 进阶 主题与插件深度定制
- 源码主题定制
- 克隆 swagger-ui 仓库，修改 Sass 变量（如主色、按钮样式），重新构建，生成带品牌色的静态包
- 插件与布局
- 通过 Presets + Plugins 架构扩展功能与替换布局，例如多关键词过滤、企业 Header、隐藏元素等
- 适用场景
实用建议与常见问题
- 规范与版本
- 确认使用 Swagger 2.0 还是 OpenAPI 3.x，两者在字段上存在差异；保持规范与后端代码、网关校验一致
- 性能与体验
- 大型文档建议默认折叠：docExpansion: ‘none’；持久化授权：persistAuthorization: true
- 鉴权与网络
- 若后端在 127.0.0.1 或内网，请在 Swagger UI 的 requestInterceptor 中设置后端地址或代理头，避免跨域与 404
- 部署与维护
- 将 swagger.yaml 纳入代码仓库，配合 CI 自动部署静态包或重启 Node 服务
- 锁定 Swagger UI 版本，避免升级导致样式/配置不兼容
