Ubuntu 上 Swagger 容器化部署指南
一 准备环境
- 在 Ubuntu 20.04/22.04 上安装 Docker（建议 20.10+），并启动服务：
- 安装：sudo apt update && sudo apt install -y docker.io
- 启动与开机自启：sudo systemctl start docker && sudo systemctl enable docker
- 可选：安装 Docker Compose 以便编排多服务（示例命令：sudo curl -L “https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)” -o /usr/local/bin/docker-compose && sudo chmod +x /usr/local/bin/docker-compose）。
二 快速部署 Swagger UI
- 使用官方镜像一键启动（容器内默认端口为 8080，映射到主机 8080）：
- 命令：docker run -d -p 8080:8080 --name swagger-ui swaggerapi/swagger-ui
- 访问：打开浏览器进入 http://localhost:8080 查看 Swagger UI 页面。
- 常用环境变量（示例）：
- 指定远程规范：docker run -d -p 8080:8080 -e SWAGGER_JSON_URL=https://api.example.com/openapi.json swaggerapi/swagger-ui
- 指定本地规范文件：docker run -d -p 8080:8080 -v /path/to/swagger.json:/app/swagger.json -e SWAGGER_JSON=/app/swagger.json swaggerapi/swagger-ui
- 多规范切换：docker run -d -p 8080:8080 -e “URLS=[{url:‘/specs/v1.json’,name:‘V1’},{url:‘/specs/v2.json’,name:‘V2’}]” -v /path/to/specs:/usr/share/nginx/html/specs swaggerapi/swagger-ui
- 说明：官方镜像基于 Nginx/Alpine，体积小、适合生产使用。
三 部署 Swagger Editor
- 使用官方镜像运行编辑器（容器内端口 8080）：
- 命令：docker run -d -p 8081:8080 --name swagger-editor swaggerapi/swagger-editor:latest
- 访问：打开浏览器进入 http://localhost:8081 使用在线编辑与预览。
- 更新方式：停止并删除旧容器后拉取最新镜像重启即可（见下文“更新与回滚”）。
四 使用 Docker Compose 编排与多实例
- 单服务编排示例（将主机 80 映射到容器 8080，并挂载本地规范目录与 Nginx 配置）：
- 文件：docker-compose.yml
version: ‘3.8’
services:
swagger-ui:
image: swaggerapi/swagger-ui
container_name: swagger-ui
ports:
- “80:8080”
environment:
- SWAGGER_JSON_URL=/specs/openapi.json
- BASE_URL=/api-docs
volumes:
- ./specs:/usr/share/nginx/html/specs
- ./nginx/conf.d:/etc/nginx/conf.d
restart: always
healthcheck:
test: [“CMD”, “wget”, “–no-verbose”, “–tries=1”, “–spider”, “http://localhost:8080/api-docs/health”]
interval: 30s
timeout: 10s
retries: 3
- 启动：docker-compose up -d
- 多实例/集群示例（多端口对外提供多个 UI 实例，便于横向扩展与灰度）：
- 文件：docker-compose.yml
version: ‘3.8’
services:
ui-1:
image: swaggerapi/swagger-ui
ports: [“8081:8080”]
environment:
- SWAGGER_JSON_URL=/specs/openapi.json
volumes: [“./specs:/usr/share/nginx/html/specs”]
ui-2:
image: swaggerapi/swagger-ui
ports: [“8082:8080”]
environment:
- SWAGGER_JSON_URL=/specs/openapi.json
volumes: [“./specs:/usr/share/nginx/html/specs”]
- 启动：docker-compose up -d
- 说明：多实例适合高可用与分流；也可在前端接入 Nginx/Ingress 做统一域名与负载均衡。
五 生产化与安全加固
- HTTPS 与访问控制：挂载自定义 Nginx 配置与证书，仅开放 443，按需限制来源 IP：
- 挂载：docker run -d -p 443:443 -v /path/to/custom-nginx.conf:/etc/nginx/conf.d/default.conf -v /path/to/ssl:/etc/nginx/ssl swaggerapi/swagger-ui
- 配置要点：listen 443 ssl; ssl_certificate/ssl_certificate_key 指向证书；可加入 allow/deny 规则限制网段。
- 数据与配置持久化：将 /usr/share/nginx/html/specs（规范文件）、/etc/nginx/conf.d（Nginx 配置）、/etc/nginx/ssl（证书）挂载到宿主机，避免容器重建丢失。
- 高可用与健康检查：在 docker-compose.yml 中配置 restart: always 与 healthcheck，并接入反向代理/负载均衡实现故障转移与滚动更新。
- 更新与回滚：
- 拉取新镜像：docker pull swaggerapi/swagger-ui
- 重启服务：docker-compose up -d --force-recreate（或 docker restart ）
- 回滚：保留旧镜像标签，切换镜像版本后重启；多实例时逐个滚动更新降低影响。
