Swagger在CentOS上如何部署 - 问答

在 CentOS 上部署 Swagger 的可选方案

使用 Node.js 运行 Swagger Editor 与 Swagger UI（适合离线编写与展示 OpenAPI/Swagger 文档）
使用 Python Flask + swagger-ui-express（适合将文档集成到现有 Python 服务）
使用 Docker 快速起一个 Swagger UI 容器（最省事，适合演示与临时环境）
使用 Nginx/Apache 托管静态 Swagger UI（适合生产静态托管与反向代理）

方案一 Node.js 部署 Swagger Editor 与 Swagger UI

安装 Node.js 与 npm
- 安装编译依赖与 NodeSource 仓库，然后安装 Node.js 12.x（也可选择更高版本）：
  - 命令：
    - yum install -y gcc-c++ make
    - curl -sL https://rpm.nodesource.com/setup_12.x | bash -
    - yum install -y nodejs
    - node -v && npm -v
部署 Swagger Editor
- 命令：
  - mkdir -p /opt/swagger && cd /opt/swagger
  - wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz
  - tar -xf v3.14.0.tar.gz && cd swagger-editor-3.14.0
  - npm install -g http-server
  - http-server -p 8080
- 访问：http://<服务器IP>:8080
部署 Swagger UI
- 命令：
  - cd /opt/swagger
  - wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz
  - tar -xf v3.34.0.tar.gz && cd swagger-ui-3.34.0
  - npm init -y
  - npm install express --save
  - mkdir public
  - cp -r swagger-ui-3.34.0/dist/* public/
- 创建服务入口 /opt/swagger/swagger-ui/index.js：
  - 内容：
    - const express = require(‘express’);
    - const app = express();
    - app.use(‘/static’, express.static(‘public’));
    - app.get(‘/’, (req, res) => res.send(‘Swagger UI is running. See /static/index.html’));
    - app.listen(3000, () => console.log(‘Swagger UI listening on 3000’));
- 启动：node /opt/swagger/swagger-ui/index.js
- 访问：http://<服务器IP>:3000/static/index.html
展示自定义文档
- 将你的 OpenAPI/Swagger JSON 放到 /opt/swagger/swagger-ui/public/（如：api.yaml 或 swagger.json）
- 编辑 /opt/swagger/swagger-ui/public/index.html，将默认 URL（如 petstore）改为你的文件：
  - 例如：url: ‘/static/your-swagger.json’（或 /static/api.yaml）
- 刷新页面即可加载自定义文档

方案二 Python Flask 集成 Swagger UI

安装依赖
- yum install -y python3 python3-pip
- pip3 install flask flask-swagger-ui
最小可用示例 /opt/swagger/app.py
- 代码：
  - from flask import Flask
  - from flask_swagger_ui import get_swaggerui_blueprint
  - app = Flask(name)
  - SWAGGER_URL = ‘/api-docs’
  - API_URL = ‘/static/swagger.json’ # 可改为远程地址
  - swaggerui_blueprint = get_swaggerui_blueprint(SWAGGER_URL, API_URL, config={‘app_name’: “My API Docs”})
  - app.register_blueprint(swaggerui_blueprint, url_prefix=SWAGGER_URL)
  - @app.route(‘/static/path:filename’)
  - def static_files(filename):
  - ```
  from flask import send_from_directory
```
- ```
return send_from_directory('static', filename)
```
  - if name == ‘main’:
  - ```
  app.run(host='0.0.0.0', port=5000)
```
运行与访问
- 将 swagger.json 放到 /opt/swagger/static/
- python3 /opt/swagger/app.py
- 访问：http://<服务器IP>:5000/api-docs

方案三 Docker 快速部署 Swagger UI

安装 Docker
- yum install -y docker
- systemctl start docker && systemctl enable docker
运行容器
- 命令：docker run -d -p 80:8080 swaggerapi/swagger-ui
- 说明：容器默认将 /usr/share/nginx/html 下的页面暴露在 8080 端口，本例映射到宿主 80 端口
访问：http://<服务器IP>/
使用自定义文档
- 方式 A：挂载本地目录到容器内并修改页面指向你的 JSON
- 方式 B：使用环境变量指定 URL（部分镜像支持，如 swaggerapi/swagger-ui 支持 SWAGGER_JSON 环境变量）

方案四使用 Nginx 托管静态 Swagger UI

构建静态文件
- 可直接使用方案一中下载的 swagger-ui/dist 目录内容，或解压官方发布包到 /usr/share/nginx/html/swagger
配置 Nginx
- 示例 /etc/nginx/conf.d/swagger.conf：
  - server {
    - listen 80;
    - server_name your.domain.com;
    - root /usr/share/nginx/html/swagger;
    - index index.html;
    - location / {
      - try_files $uri $uri/ /index.html;
      - }
    - }
- 检查并重载：nginx -t && systemctl reload nginx
访问：http://<服务器IP|域名>/
提示：如需反向代理后端 API，可在同一 server 下增加 location /api/ { proxy_pass http://127.0.0.1:8080; }

防火墙与访问验证

放行端口（以 firewalld 为例）
- firewall-cmd --zone=public --add-port=3000/tcp --permanent
- firewall-cmd --zone=public --add-port=8080/tcp --permanent
- firewall-cmd --reload
访问测试
- 浏览器打开：http://<服务器IP>:8080（Editor）、http://<服务器IP>:3000/static/index.html（UI）、http://<服务器IP>:5000/api-docs（Flask）
常见问题排查
- 端口未放行或占用：ss -tulpen | grep -E ‘3000|8080|5000’
- 静态资源 404：确认 JSON/YAML 已放在正确目录，且 index.html 的 url 指向正确路径
- 容器无法访问：确认 Docker 运行且端口映射正确（docker ps、docker logs）

0 赞

0 踩