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 用户运行并只读挂载配置。

最新问答

相关标签