如何用Linux部署Swagger

在 Linux 上部署 Swagger（通常指 Swagger UI） 常见有几种方式，下面按从简单到完整给你说明，适用于 API 文档展示 / 接口调试 场景。

一、方式一：最简单（直接部署 Swagger UI 静态页面）

适合：
✅ 只需要查看和调试接口
✅ 已有 swagger.json 或 swagger.yaml

1️⃣ 安装 Nginx（如果没有）

# CentOS / Rocky / Alma
sudo yum install -y nginx

# Ubuntu / Debian
sudo apt update
sudo apt install -y nginx

启动 Nginx：

sudo systemctl start nginx
sudo systemctl enable nginx

2️⃣ 下载 Swagger UI

cd /usr/share/nginx/html
sudo git clone https://github.com/swagger-api/swagger-ui.git

或下载指定版本：

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.zip
unzip v5.17.14.zip

3️⃣ 配置 Swagger UI

进入 dist 目录：

cd swagger-ui/dist

编辑 swagger-initializer.js：

window.onload = function () {
  SwaggerUIBundle({
    url: "http://你的IP或域名/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis
    ]
  })
}

4️⃣ 放置你的 API 文档

将 swagger.json 放到 Nginx 目录：

cp swagger.json /usr/share/nginx/html/

访问：

http://服务器IP/swagger-ui/dist/

✅ 完成

二、方式二：Docker 部署 Swagger UI（推荐）

适合：
✅ 快速、干净、不污染系统
✅ 服务器环境

1️⃣ 安装 Docker

# CentOS
sudo yum install -y docker
sudo systemctl start docker

# Ubuntu
sudo apt install -y docker.io

2️⃣ 启动 Swagger UI

docker run -d \
  -p 8080:8080 \
  -e SWAGGER_JSON=/tmp/swagger.json \
  -v /path/to/swagger.json:/tmp/swagger.json \
  swaggerapi/swagger-ui

访问：

http://服务器IP:8080

三、方式三：Spring Boot + Swagger（后端集成）

适合：
✅ Java 项目
✅ 自动生成接口文档

1️⃣ 引入依赖（Springfox 或 springdoc）

✅ 推荐 springdoc（Spring Boot 2.6+）

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

2️⃣ 访问地址

http://服务器IP:8080/swagger-ui.html

或：

http://服务器IP:8080/swagger-ui/index.html

四、方式四：Swagger Editor（编写 API）

适合：
✅ 编写 OpenAPI 文档

docker run -d -p 8081:8080 swaggerapi/swagger-editor

访问：

http://服务器IP:8081

五、常见问题

✅ 1. 跨域问题

如果 swagger.json 来自其他服务，需要后端允许 CORS：

@CrossOrigin("*")

或 Nginx：

add_header Access-Control-Allow-Origin *;

✅ 2. 权限问题

确保 Nginx 有权限读取文件：

chmod -R 755 /usr/share/nginx/html

六、推荐方案总结

如果你愿意，可以告诉我：

• ✅ 是否 Java / Python / Node
• ✅ 是否已有 swagger.json
• ✅ 是否用 Docker / 物理机

我可以给你 精确到命令级别 的方案。