debian swagger怎样集成nginx

在 Debian 上把 Swagger（如 Swagger UI / Swagger Editor）通过 Nginx 对外提供访问，通常有三种常见场景。下面按“最常用方案”给你一个清晰、可落地的集成方式。

一、常见架构说明（先选一种）

方案 A：静态 Swagger UI（最推荐）

Swagger UI 是纯前端
Nginx 直接托管静态文件
后端 API 通过 Nginx 反代

✅ 简单、稳定、生产常用

方案 B：Swagger UI + 后端 API 同域

Nginx 同时托管：
- / → Swagger UI
- /api/ → 后端服务

方案 C：Swagger Editor（在线编辑）

类似方案 A，但用 Swagger Editor

二、Debian 安装 Nginx

sudo apt update
sudo apt install nginx -y

验证：

systemctl status nginx

三、部署 Swagger UI（静态方式）

1. 下载 Swagger UI

cd /var/www
sudo wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.zip
sudo apt install unzip -y
sudo unzip v5.17.14.zip
sudo mv swagger-ui-5.17.14 swagger-ui

2. 配置 Swagger JSON 路径

编辑：

sudo nano /var/www/swagger-ui/dist/swagger-initializer.js

修改：

url: "https://your-domain.com/api/openapi.json",

或本地：

url: "/swagger/api.json",

3. Nginx 配置

新建配置文件：

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

示例（最常用）：

server {
    listen 80;
    server_name swagger.example.com;

    root /var/www/swagger-ui/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 后端 API
    location /api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

启用：

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

四、本地 API JSON 示例

如果你用本地文件：

sudo cp openapi.json /var/www/swagger-ui/dist/api.json

Swagger UI 中：

url: "/api.json"

五、HTTPS（推荐）

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d swagger.example.com

六、常见问题

1. Swagger 无法加载 JSON

跨域问题 → 后端加 CORS
Nginx 代理路径错误

2. 404

try_files 没写
root 路径不对

3. 想隐藏 Swagger

location /swagger/ {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

七、如果你用的是 Spring Boot

常见做法：

Spring 提供 /v3/api-docs
Nginx 反代
Swagger UI 指向该地址

如果你能告诉我：

用的是 Swagger UI / Editor / Springdoc
后端语言（Java / Go / Node）
是否要 HTTPS / 鉴权

我可以给你 完全定制的 Nginx 配置。