Swagger UI 与 OpenAPI 文档发布最完整实战教程（2025 年最新版）
目标：让你 5 分钟内拥有一个漂亮、可在线调用、支持多环境的对外 API 文档页面。
一、Swagger UI 是什么？
Swagger UI = 把一个 OpenAPI（JSON/YAML）文件渲染成漂亮的、可直接点着试的交互式文档页面（如图）。
二、2025 年最常用 4 种发布方式（从简单到专业）
| 方式 | 适用场景 | 部署难度 | 推荐指数 |
|---|---|---|---|
| 1. 项目内置（最常见） | 内部开发、测试、联调 | ★☆☆☆☆ | ★★★★★ |
| 2. 静态托管（最推荐对外发布） | 对外开放文档、给合作伙伴看 | ★★☆☆☆ | ★★★★★ |
| 3. Redoc（更漂亮的替代品） | 对外产品文档、官网展示 | ★★☆☆☆ | ★★★★☆ |
| 4. 专业文档平台 | 多项目、多版本、权限控制 | ★★★★☆ | ★★★☆☆ |
下面逐个手把手教你部署。
1. 项目内置 Swagger UI（5 分钟搞定，99% 项目都在用）
Spring Boot 3 + springdoc（2025 主流）
# application.yml
springdoc:
swagger-ui:
path: /swagger-ui.html # 访问地址
enabled: true
api-docs:
enabled: true
path: /v3/api-docs # JSON地址
# 多环境控制（只在 dev/test 开启）
springdoc:
swagger-ui:
enabled: ${SWAGGER_ENABLED:true}访问地址（启动项目后）：
- 文档页面：http://localhost:8080/swagger-ui.html
- JSON 文件：http://localhost:8080/v3/api-docs
- YAML 文件：http://localhost:8080/v3/api-docs.yaml
生产环境关闭文档（推荐）
# application-prod.yml
springdoc:
swagger-ui:
enabled: false
api-docs:
enabled: false2. 静态托管方式（对外发布首选，零服务器成本）
步骤（3 分钟完成）：
- 获取你的 openapi.json 或 openapi.yaml 文件
（项目启动后访问 /v3/api-docs 复制，或直接从代码生成） - 去这个网站一键生成静态文档（2025 最火）
https://scalar.com/openapi
或 https://swagger-ui.netlify.app （新版支持直接粘贴） - 最简单粗暴方式（GitHub + Netlify/Vercel，永久免费）： 创建一个空仓库，放入 2 个文件：
your-api-docs/
├── openapi.yaml ← 你的接口定义文件
└── index.html ← 下面这段代码index.html 内容（复制粘贴即可）：
<!DOCTYPE html>
<html>
<head>
<title>我的商城 API 文档</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
<script>
window.onload = function() {
const ui = SwaggerUIBundle({
url: "./openapi.yaml", // 或 openapi.json
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
],
layout: "BaseLayout",
deepLinking: true,
showExtensions: true,
defaultModelsExpandDepth: -1, // 隐藏Models区
});
};
</script>
</body>
</html>- 推到 GitHub → 用 Vercel / Netlify 一键导入仓库 → 自动生成网址
示例：https://my-shop-api.vercel.app
优点：零成本、全球 CDN 加速、支持自定义域名、支持 Basic/OAuth 认证
3. 用 Redoc 发布（比 Swagger UI 更漂亮，适合对外官网）
一行命令本地预览：
npx redoc-cli serve openapi.yaml --port 8080生成静态页面：
npx redoc-cli bundle openapi.yaml -o redoc.htmlRedoc 在线快速发布（推荐）：
https://redocly.com/redoc-quickstart/
直接拖入 yaml 文件 → 立即得到分享链接
4. 专业文档平台（大厂/多项目用）
| 工具 | 特点 | 价格 |
|---|---|---|
| Apifox | 国产最强，文档+Mock+测试一体 | 免费版够用 |
| ShowDoc | 轻量级，国内最流行 | 免费+付费 |
| YApi | 阿里巴巴出品，老牌 | 免费自部署 |
| SwaggerHub | OpenAPI 官方出品 | 免费版有限制 |
| Optic | 自动检测接口变更 | 付费为主 |
推荐发布组合（2025 最佳实践）
| 场景 | 推荐方案 |
|---|---|
| 内部开发联调 | 项目内置 springdoc（swagger-ui.html） |
| 给合作伙伴看 | Vercel/Netlify 静态托管 Swagger UI |
| 对外产品文档 | Redoc 静态页 + 自定义域名 |
| 多团队多项目 | Apifox 或自部署 YApi |
需要我直接给你打包一个「已美化 + 深色主题 + 自定义LOGO + 支持Bearer登录」的完整静态文档模板吗？3 个文件压缩包，扔到任意静态托管就行。直接回复“发我模板”即可。
