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 参数）

最新问答

相关标签