Swagger在CentOS上如何集成

Swagger在CentOS上的集成步骤

一、环境准备：安装必要工具

在集成Swagger前，需确保CentOS系统具备Node.js（用于运行Swagger UI/Editor）和Git（用于克隆项目）环境。

1. 更新系统：运行sudo yum update -y同步系统软件包。
2. 安装Node.js和npm：
   • 安装编译依赖：sudo yum install -y gcc-c++ make。
   • 添加NodeSource官方仓库（以Node.js 14.x为例）：curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -。
   • 安装Node.js及npm：sudo yum install -y nodejs。
   • 验证安装：node -v（应输出版本号，如v14.17.0）、npm -v（应输出版本号，如6.14.13）。

二、集成方式选择（三种常见方案）

方案1：使用Swagger UI（静态文档展示）

Swagger UI是交互式API文档界面，适合快速查看和测试API。

1. 下载并解压Swagger UI：

   mkdir -p /opt/swagger && cd /opt/swagger
   wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.34.0.tar.gz
   tar -xzf v3.34.0.tar.gz
   cd swagger-ui-3.34.0
   

2. 安装依赖并配置静态资源：

   npm install express --save
   mkdir public
   cp -r dist/* public/
   

3. 创建启动脚本：
   新建index.js，内容如下：

   const express = require('express');
   const app = express();
   app.use('/static', express.static('public'));
   app.listen(3000, () => console.log('Swagger UI running on port 3000'));
   

4. 启动服务：node index.js。
5. 访问文档：在浏览器输入http://<服务器IP>:3000/static/index.html，即可看到Swagger UI界面。

方案2：使用Swagger Editor（动态编辑文档）

Swagger Editor支持在线编写OpenAPI规范（YAML/JSON），并实时预览文档。

1. 下载并解压Swagger Editor：

   cd /opt/swagger
   wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz
   tar -xzf v3.14.0.tar.gz
   cd swagger-editor-3.14.0
   

2. 启动Editor服务：

   npm install -g http-server
   http-server -p 8080
   

3. 访问Editor：在浏览器输入http://<服务器IP>:8080，即可在线编写API文档。

方案3：使用Docker（快速部署）

若系统已安装Docker，可通过镜像快速部署Swagger UI。

1. 安装Docker：

   sudo yum install -y docker
   sudo systemctl start docker
   sudo systemctl enable docker
   

2. 拉取并运行Swagger UI镜像：

   docker pull swaggerapi/swagger-ui
   docker run -d -p 80:8080 --name swagger-ui swaggerapi/swagger-ui
   

3. 访问文档：在浏览器输入http://<服务器IP>，即可看到Swagger UI界面（镜像默认指向PetStore示例API，可替换为自定义API地址）。

三、配置自定义API文档

无论选择哪种方案，均需将自定义API文档集成到Swagger中：

1. 编写API描述文件：使用OpenAPI规范（YAML/JSON）编写文档，例如swagger.yaml或swagger.json。
2. 放置文档到静态目录：
   • 若使用Swagger UI，将文档复制到/opt/swagger/public目录（如cp swagger.yaml /opt/swagger/public）。
   • 若使用Swagger Editor，直接在Editor界面点击“Import File”上传文档。
3. 修改配置指向自定义文档：
   • 若使用Swagger UI，编辑public/index.html，找到url: "https://petstore.swagger.io/v2/swagger.json"，替换为url: "/static/your-swagger-file.json"。
   • 若使用Swagger Editor，无需修改，默认支持本地文件上传。

四、注意事项

• 防火墙设置：确保CentOS防火墙开放对应端口（如Swagger UI的3000端口、Swagger Editor的8080端口），运行sudo firewall-cmd --add-port=3000/tcp --permanent并sudo firewall-cmd --reload。
• HTTPS配置：生产环境建议使用HTTPS（如通过Let’s Encrypt申请免费证书），避免API文档被拦截。
• 版本兼容性：根据需求选择Swagger UI/Editor的版本（如最新稳定版），避免因版本过旧导致功能缺失。