在 Debian 上部署 Swagger 的可行路径
- 使用 Node.js + Express + swagger-ui-express 托管文档
- 使用 Docker 运行 swaggerapi/swagger-ui 镜像
- 在 Java/Spring Boot 项目中集成 Swagger UI（springfox 或 springdoc-openapi）
- 使用 Python/Flask 集成 Flasgger 提供文档页面
方案一 Node.js Express 托管 Swagger UI
- 安装依赖
- 更新系统并安装 Node.js/npm：sudo apt update && sudo apt install -y nodejs npm
- 准备文档
- 新建目录并初始化：mkdir swagger-demo && cd swagger-demo && npm init -y
- 安装中间件：npm install express swagger-ui-express yamljs
- 创建规范文件 swagger.yaml（示例）：
swagger: ‘2.0’
info:
title: Sample API
description: A sample API
version: ‘1.0.0’
host: localhost:3000
basePath: /
schemes:
- http
paths:
/hello:
get:
summary: Say hello
responses:
‘200’:
description: OK
- 启动服务 app.js
- const express = require(‘express’);
const swaggerUi = require(‘swagger-ui-express’);
const YAML = require(‘yamljs’);
const app = express();
const swaggerDocument = YAML.load(‘./swagger.yaml’);
app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(
Server on ${PORT}));
- 运行：node app.js
- 访问文档：打开浏览器访问 http://服务器IP:3000/api-docs
- 生产建议
- 用 PM2 守护进程：sudo npm i -g pm2 && pm2 start app.js --name swagger-ui
- 用 Nginx 反向代理（示例）：
- 安装：sudo apt install -y nginx
- 站点配置 /etc/nginx/sites-available/swagger：
server {
listen 80; server_name your_domain_or_ip;
location /api-docs/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
- 启用站点并重启：sudo ln -s /etc/nginx/sites-available/swagger /etc/nginx/sites-enabled && sudo nginx -t && sudo systemctl restart nginx
方案二 Docker 快速部署 Swagger UI
- 安装 Docker：sudo apt update && sudo apt install -y docker.io
- 运行容器（将本地 8080 映射到容器 8080）：
- docker run -d -p 8080:8080 swaggerapi/swagger-ui
- 访问文档：打开浏览器访问 http://服务器IP:8080
- 说明
- 容器内置 Swagger UI，适合快速演示与隔离部署；如需自定义配置，可通过环境变量或挂载自定义页面资源
方案三 Java Spring Boot 集成 Swagger UI
- 准备环境：sudo apt update && sudo apt install -y openjdk-11-jdk maven
- 添加依赖（Maven，示例使用 springfox-boot-starter 3.x）
-
io.springfox
springfox-boot-starter
3.0.0
- 启动应用：./mvnw spring-boot:run 或打包后 java -jar target/app.jar
- 访问文档：打开浏览器访问 http://服务器IP:8080/swagger-ui.html
- 提示
- Springfox 3.x 默认路径为 /swagger-ui.html；如使用 springdoc-openapi（替代方案），常见路径为 /swagger-ui.html 或 /swagger-ui/，以所用版本为准
方案四 Python Flask 集成 Flasgger
- 安装依赖：sudo apt update && sudo apt install -y python3 python3-pip && pip3 install flask flasgger
- 最小示例 app.py
- from flask import Flask
from flasgger import Swagger
app = Flask(name)
swagger_config = {
“headers”: [],
“specs”: [{
“endpoint”: ‘apispec_1’,
“route”: ‘/apispec_1.json’,
“rule_filter”: lambda rule: True,
“model_filter”: lambda tag: True
}],
“static_url_path”: “/flasgger_static”,
“swagger_ui”: True,
“specs_route”: “/swagger/”
}
Swagger(app, config=swagger_config)
@app.route(‘/hello’)
def hello():
return {“message”: “Hello, Swagger”}
if name == ‘main’:
app.run(host=‘0.0.0.0’, port=5000)
- 访问文档：打开浏览器访问 http://服务器IP:5000/swagger/
- 说明
- Flasgger 支持从代码注释或 YAML 生成规范，适合在现有 Flask 项目中快速接入
通用优化与安全建议
- 启用 HTTPS（Nginx + Let’s Encrypt），对外仅暴露 443，关闭 80 或做重定向
- 配置 防火墙（如 UFW）：sudo ufw allow 80,443/tcp && sudo ufw enable
- 生产访问控制：为文档路径（如 /api-docs 或 /swagger）增加 Basic Auth/Token 或仅内网开放
- 规范维护：将 swagger.yaml/openapi.yaml 纳入版本控制，与代码同步更新
- 静态资源缓存：对 UI 静态资源设置合适的 Cache-Control，避免频繁变更不生效
