debian怎么部署swagger

在 Debian 上“部署 Swagger”通常有两种常见场景，下面分别说明，你可以按需选择。

一、只是查看 / 调试已有项目的 API（最常用）

方案 1：使用 Swagger UI（静态页面）

适合：已有 OpenAPI / Swagger JSON 文件

1. 安装依赖

sudo apt update
sudo apt install -y nginx curl unzip

2. 下载 Swagger UI

cd /var/www
sudo curl -L https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.zip -o swagger-ui.zip
sudo unzip swagger-ui.zip
sudo mv swagger-ui-5.17.14 swagger-ui

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;
    }
}

启用站点：

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

4. 修改 API 地址

编辑：

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

修改：

url: "https://your-api.com/v3/api-docs"

二、Java / Spring Boot 项目（后端直接集成）

方案 2：Springdoc OpenAPI（推荐）

适合：Spring Boot 项目

1. 添加依赖（Maven）

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

2. 启动后访问

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

无需额外部署，Debian 只需运行 Java 服务即可。

三、Node.js 项目（Express）

方案 3：swagger-ui-express

npm install swagger-ui-express yamljs

const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./swagger.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

访问：

http://服务器IP:3000/api-docs

四、常见问题

1. 端口被占用

sudo lsof -i:80

2. 外网无法访问

sudo ufw allow 80

3. 使用 HTTPS（推荐）

可用：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx

五、我可以进一步帮你

如果你告诉我：

• 后端语言（Java / Node / Python / Go）
• 是否已有 API 文档
• 是否要公网访问

我可以直接给你一套可复制的完整部署方案。