在 Linux 上使用 Swagger 进行 API 文档共享
一 方案总览
- 使用 Swagger Editor 在线编写与校验 OpenAPI 规范（YAML/JSON），使用 Swagger UI 将规范渲染成交互式文档页面，供团队浏览与调试。
- 文档共享的常见形态：
- 本地或内网访问：直接通过 http://服务器IP:端口 打开页面。
- 公网访问：配合 反向代理（Nginx） 或 内网穿透（如 Cpolar） 发布到公网域名或临时地址。
- 与后端集成：在 Spring Boot 等项目中自动生成文档页面，随服务一起发布。
二 快速上手 原生部署 Swagger Editor 与 Swagger UI
- 安装 Node.js 与 npm（示例为 Ubuntu/Debian）：
- 安装：sudo apt update && sudo apt install -y nodejs npm
- 验证：node -v、npm -v
- 启动 Swagger Editor（静态文件服务方式）：
- 安装静态服务器：npm install -g http-server
- 启动：http-server -p 8080（浏览器访问：http://服务器IP:8080）
- 启动 Swagger UI（以 Express 托管 dist 为例）：
- 准备目录与资源：将 Swagger UI 项目 dist 目录内容复制到 public/；创建 index.js：
- const express = require(‘express’); const app = express(); app.use(‘/swagger’, express.static(‘public’)); app.listen(3000, () => console.log(‘http://localhost:3000/swagger’));
- 启动：node index.js（浏览器访问：http://服务器IP:3000/swagger）
- 说明：Editor 用于编写/校验规范，UI 用于展示与调试，二者可分别部署在不同端口。
三 使用 Docker 部署 推荐
- 安装 Docker（示例）：
- sudo apt-get update && sudo apt-get install -y docker.io
- 启动与开机自启：sudo systemctl start docker && sudo systemctl enable docker
- 运行容器（将容器 8080 映射到宿主机端口，避免冲突）：
- Swagger Editor：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
- Swagger UI：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
- 访问：
- Editor：http://服务器IP:38080
- UI：http://服务器IP:38081
- 提示：如需同时运行多个实例，请映射不同宿主机端口。
四 与 Spring Boot 集成 自动生成文档
- 使用 springdoc-openapi（推荐，基于 OpenAPI 3）：
- Maven 依赖：
-
org.springdoc
springdoc-openapi-starter-webmvc-ui
2.1.0
- 配置（可选）：application.properties
- springdoc.api-docs.path=/api-docs
- springdoc.swagger-ui.path=/swagger-ui
- 访问：http://服务器IP:8080/swagger-ui
- 兼容旧项目（Springfox，基于 Swagger 2）：
- Maven 依赖：
-
io.springfox
springfox-swagger2
2.9.2
-
io.springfox
springfox-swagger-ui
2.9.2
- 访问：http://服务器IP:8080/swagger-ui.html
- 说明：新项目优先使用 springdoc，与 Spring Boot 3 / Java 17+ 生态更契合。
五 安全与远程访问建议
- 反向代理与访问控制（以 Nginx 为例，仅示例思路）：
- 配置基于 IP 或 Basic Auth 的访问控制；开启 HTTPS；将 /swagger 或 /swagger-ui 反向代理到实际服务。
- 内网穿透（无公网 IP 场景）：
- 使用 Cpolar 等工具创建公网隧道，将本地 38080/38081 或容器端口映射为临时公网地址，便于外部分享与演示。
- 基础认证示例（概念）：
- 在服务端增加 HTTP Basic Auth 中间件，对访问 /swagger 的请求进行用户名/密码校验后再转发，保护文档不被未授权访问。
