Swagger在Debian如何部署

在 Debian 上部署 Swagger（通常指 Swagger UI 或 Swagger Editor），常见做法有几种，取决于你是只想查看/测试 API，还是集成到项目中。下面按最常用场景给你一个清晰、可操作的说明。

一、部署 Swagger UI（最常见）

✅ 方式一：用 Nginx 部署 Swagger UI（推荐）

适合：

• 查看 OpenAPI 文档
• 与后端 API 分离部署

1️⃣ 安装 Nginx

sudo apt update
sudo apt install -y nginx

2️⃣ 下载 Swagger UI

cd /var/www/html
sudo git clone https://github.com/swagger-api/swagger-ui.git

或者只取 dist：

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

3️⃣ 配置 Nginx

编辑配置：

sudo nano /etc/nginx/sites-available/swagger

内容示例：

server {
    listen 80;
    server_name your-domain-or-ip;

    location / {
        root /var/www/html/swagger-ui;
        index index.html;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/swagger /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

4️⃣ 访问

浏览器打开：

http://服务器IP

二、指定你的 OpenAPI 文件（重点）

方法 1：修改 swagger-initializer.js

nano /var/www/html/swagger-ui/swagger-initializer.js

修改：

url: "http://your-api-domain/api/openapi.yaml",

方法 2：直接替换默认 JSON

cp your-openapi.yaml /var/www/html/swagger-ui/

然后访问：

http://IP/?url=/your-openapi.yaml

三、部署 Swagger Editor（在线编辑 API）

1️⃣ 下载 Swagger Editor

cd /var/www/html
git clone https://github.com/swagger-api/swagger-editor.git

2️⃣ 用 Nginx 提供静态文件

location /editor {
    root /var/www/html/swagger-editor;
    index index.html;
}

访问：

http://IP/editor

四、Docker 方式（最简单）

如果你已安装 Docker：

Swagger UI

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/api/openapi.yaml \
  -v $(pwd):/usr/share/nginx/html/api \
  swaggerapi/swagger-ui

Swagger Editor

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

五、与 Java / Spring Boot 集成（补充）

如果你用的是 Spring Boot：

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

访问：

http://localhost:8080/swagger-ui.html

六、常见问题

❓ 404 / 无法加载 API

• OpenAPI 文件必须是 HTTP 可访问
• 不能跨域（CORS）限制

❓ Debian 防火墙

sudo ufw allow 80

七、推荐方案总结

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

• 你用的是 Java / Node / Python？
• 想 本地部署 还是 服务器？
• OpenAPI 文件是 YAML 还是 JSON？

我可以给你完全定制的部署方案。