swagger UI在ubuntu如何部署

在 Ubuntu 上部署 Swagger UI 的三种常用方式

• 使用 Node.js + Express + swagger-ui-express（适合已有后端服务，快速集成）
• 使用 Docker（环境隔离、部署简单）
• 使用 Nginx/Apache 静态托管（仅做文档展示，不依赖 Node）

方式一 Node.js + Express 集成

• 安装依赖
  • 更新并安装 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
• 准备 API 文档
  • 新建 swagger.yaml（示例）：

    openapi: 3.0.0
    info:
      title: Sample API
      version: 1.0.0
    paths:
      /users:
        get:
          summary: List users
          responses:
            '200':
              description: OK
    

• 启动服务（server.js）

  const express = require('express');
      
  const swaggerUi = require('swagger-ui-express');
      
  const YAML = require('yamljs');
      
  const swaggerDocument = YAML.load('./swagger.yaml');
      
  
  const app = express();
      
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
      
  
  const PORT = process.env.PORT || 3000;
      
  app.listen(PORT, () =>
   console.log(`Server running on :${
  PORT}
      `));
      
  

  • 运行：node server.js
  • 访问：http://localhost:3000/api-docs
• 说明
  • 也可使用 swagger.json，将 YAML 改为 JSON 加载方式（如 require 或 fs.readFileSync + JSON.parse）。

方式二 Docker 部署

• 安装 Docker
  • sudo apt update & & sudo apt install -y docker.io
• 运行 Swagger UI 容器（内置示例）
  • docker run -d -p 8080:8080 swaggerapi/swagger-ui-express
  • 访问：http://localhost:8080
• 挂载本地文档
  • JSON：docker run -d -p 8080:8080 -e SWAGGER_JSON=/app/swagger.json -v $(pwd):/app swaggerapi/swagger-ui-express
  • YAML：docker run -d -p 8080:8080 -e SWAGGER_YAML=/app/swagger.yaml -v $(pwd):/app swaggerapi/swagger-ui-express
  • 访问：http://localhost:8080
• 说明
  • 适合无 Node 环境的快速部署与演示，也可放入生产编排（如 docker-compose/k8s）。

方式三 静态托管 Nginx 或 Apache

• 准备静态文件
  • 下载官方发布包：wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
  • 解压并将 dist 目录内容复制到站点目录（如 /var/www/html/swagger-ui）
• 配置 Swagger UI 指向你的文档
  • 编辑 /var/www/html/swagger-ui/index.html，将 url 改为你的 swagger.json 或 swagger.yaml 地址（可为相对路径或完整 URL）
• Nginx 示例
  • root /var/www/html; index index.html;
  • 访问：http://your_server_ip/swagger-ui
• Apache 示例
  • 将文件放入 /var/www/html/swagger-ui 后启用站点并重启服务
• 说明
  • 静态托管最省资源，适合只做文档浏览；若文档在远程服务，需保证可跨域访问或在同一域名下。

常见问题与优化

• 访问被拒绝或端口不通
  • 开放防火墙端口（如 3000/8080）：sudo ufw allow 3000,8080/tcp
  • 云服务器需配置安全组放行对应端口
• 文档跨域
  • 静态托管时，将文档与 UI 同源，或在文档服务开启 CORS
• 生产建议
  • 使用 Nginx 反向代理统一端口与证书（HTTPS）
  • 将文档纳入 CI/CD，变更自动部署
  • 为 UI 设置基础路径（Swagger UI 配置中的 url 与 spec 参数）

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！