Ubuntu Swagger与Docker如何搭配使用

**在 Ubuntu 上，使用 Docker 运行 Swagger Editor 与 Swagger UI 是最简便、可移植性最好的方式。**下面给出从准备环境到多服务编排的完整操作指引，并包含与后端 API 联动与常见问题处理。

一 准备环境

• 安装 Docker（Ubuntu 20.04/22.04 示例）：
  • 更新索引并安装依赖：sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  • 添加 Docker GPG 密钥与仓库：
    • curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
    • echo “deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  • 安装并启动 Docker：sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io && sudo systemctl enable --now docker
  • 验证：sudo docker run --rm hello-world
• 可选安装 Docker Compose（便于多容器编排）：sudo apt install -y docker-compose-plugin 或参考官方二进制安装方式。

二 使用 Docker 运行 Swagger Editor 与 Swagger UI

• 拉取官方镜像（建议固定版本）：
  • docker pull swaggerapi/swagger-editor:v4.6.0
  • docker pull swaggerapi/swagger-ui:v4.15.5
• 启动容器（示例将主机端口映射为 38080/38081）：
  • Swagger Editor：docker run -d --name swagger-editor -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
  • Swagger UI：docker run -d --name swagger-ui -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
• 访问：
  • Editor：http://localhost:38080
  • UI：http://localhost:38081
• 说明：Swagger Editor 默认加载在线示例规范；Swagger UI 首次访问为空，需要导入 swagger.yaml/swagger.json 或在页面中配置 URL。

三 使用 Docker Compose 编排

• 创建 docker-compose.yml：
  • version: ‘3.8’ services: swagger-editor: image: swaggerapi/swagger-editor:v4.6.0 ports: - “38080:8080” swagger-ui: image: swaggerapi/swagger-ui:v4.15.5 ports: - “38081:8080”
• 启动：docker compose up -d（或 docker-compose up -d）
• 访问同上，Compose 便于统一启停与后续扩展（如反向代理、多实例）。

四 加载本地 OpenAPI 规范与对接后端 API

• 方式一（推荐）卷挂载 + 环境变量指定规范文件：
  • 将规范文件放到项目目录（如 ./openapi.yaml），启动 UI 容器：
    • docker run -d --name swagger-ui -p 38081:8080
      -e SWAGGER_JSON=/usr/share/nginx/html/swagger.yaml
      -v $(pwd)/openapi.yaml:/usr/share/nginx/html/swagger.yaml:ro
      swaggerapi/swagger-ui:v4.15.5
  • 说明：不同镜像中默认 HTML 静态文件目录可能不同，常见为 /usr/share/nginx/html 或 /app。如使用官方 swaggerapi/swagger-ui，上述路径通常有效；如不确定，可进入容器查看默认页面或通过自定义 Dockerfile 调整。
• 方式二 在容器内放置文件并指定路径：
  • 将文件拷入镜像或通过卷挂载到容器内某路径，然后设置 SWAGGER_JSON 为该路径。
• 与后端 API 联动（解决跨域与可达性）：
  • 开发环境可在后端开启 CORS（如 Access-Control-Allow-Origin 等）；
  • 生产环境建议将 Swagger UI 与后端置于同一域名下，或通过反向代理（Nginx/Traefik）统一承载，并在 UI 配置中把服务器地址写为后端服务的实际地址（如 http://backend:8080 或 /api）。

五 常见问题与优化

• 端口占用：检查并释放端口（如 80/8080/38080/38081），或改用未占用端口映射。
• 版本固定：生产环境建议固定镜像标签（如 v4.6.0、v4.15.5），避免升级导致页面或行为变化。
• 路径与权限：挂载卷时注意文件权限与路径正确性；只读挂载（:ro）更安全。
• 多实例与扩展：如需横向扩展或对外统一入口，可在 Compose 中增加多个 UI 实例并配合反向代理/负载均衡。