Swagger如何在Ubuntu中部署

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

• 方式一 Node.js + Express + swagger-ui-express：将 Swagger UI 集成到你的后端服务，适合在现有 Node.js/Express 项目中快速提供在线文档页面。
• 方式二 静态站点 + Nginx/Apache：下载官方 Swagger UI 静态文件，用 Nginx/Apache 托管，适合纯文档展示与跨项目复用。
• 方式三 Docker：使用官方镜像运行 Swagger Editor 与 Swagger UI，部署与升级最省事，适合演示与隔离环境。

方式一 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
• 准备 API 文档（支持 YAML/JSON）
  • 新建文件 swagger.yaml：

    swagger: '2.0'
    info:
      title: Sample API
      version: '1.0.0'
    paths:
      /users:
        get:
          summary: List all users
          responses:
            '200':
              description: An array of users
              schema:
                type: array
                items:
                  $ref: '#/definitions/User'
    definitions:
      User:
        type: object
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
    required:
      - id
      - name
    

• 启动服务（示例 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 is running at http://localhost:${
  port}
      /api-docs`);
  
  }
      );
      
  

  • 运行：node app.js，访问：http://localhost:3000/api-docs。

方式二 静态站点托管 Swagger UI（Nginx/Apache）

• 准备静态文件
  • 克隆并构建 Swagger UI：

    git clone https://github.com/swagger-api/swagger-ui.git
    cd swagger-ui &
        &
         npm install &
        &
     npm run build
    

  • 部署到 Web 目录（示例 /var/www/html/swagger-ui）：

    sudo mkdir -p /var/www/html/swagger-ui
    sudo cp -r dist/* /var/www/html/swagger-ui
    

• 配置 Nginx（示例）

  server {
      
    listen 80;
      
    server_name your-domain-or-ip;
  
  
    location /swagger-ui/ {
      
      alias /var/www/html/swagger-ui/;
      
      index index.html;
  
    }
  
  }
      
  

  • 启用站点并重启：sudo ln -s /etc/nginx/sites-available/swagger /etc/nginx/sites-enabled & & sudo nginx -t & & sudo systemctl reload nginx
  • 访问：http://your-domain-or-ip/swagger-ui/（注意路径末尾的斜杠与 index.html 的 SPA 路由处理）
• 如需 Swagger Editor，可用 http-server 托管或同样放入 Nginx/Apache。

方式三 Docker 快速部署 Editor 与 UI

• 安装 Docker（如未安装）
  • sudo apt update & & sudo apt install -y docker.io
  • sudo systemctl start docker & & sudo systemctl enable docker
• 运行容器
  • Swagger Editor（端口 8080）

    docker run -d --name swagger-editor -p 8080:8080 swaggerapi/swagger-editor:latest
    

  • Swagger UI（端口 8081；将宿主机当前目录的 swagger.yaml 挂载到容器内）

    docker run -d --name swagger-ui -p 8081:8080 \
      -v $(pwd)/swagger.yaml:/usr/share/nginx/html/swagger.yaml \
      swaggerapi/swagger-ui:latest
    

  • 访问：Editor 在 http://localhost:8080，UI 在 http://localhost:8081（如使用文件挂载，UI 首页需进入 /?url=/swagger.yaml）
• 更新：停止并删除旧容器后，拉取最新镜像并重新运行即可。

常见问题与优化建议

• 访问被拒绝或端口不通：检查 UFW/云安全组 是否放行对应端口（如 3000/8080/8081），以及服务是否监听 0.0.0.0 而非仅 127.0.0.1。
• 路径与路由：Swagger UI 为 SPA，建议配置 try_files（Nginx）或在 UI 配置中设置正确的 url 指向你的 swagger.yaml。
• 文档维护：多人协作建议保留 swagger.yaml/json 在代码仓库，通过 CI/CD 自动部署到 Nginx 或容器。
• 生产建议：启用 HTTPS/反向代理、限制访问来源、为静态资源设置缓存、容器化时以 非 root 用户运行并只读挂载配置。

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