Centos Swagger如何部署

CentOS系統部署Swagger指南

Swagger是一套用于設計、構建、記錄和使用RESTful API的工具集，其中Swagger UI是常用的交互式文檔展示工具。以下是在CentOS系統上部署Swagger UI的具體步驟：

一、準備工作

1. 更新系統：確保系統為最新版本，避免依賴沖突

   sudo yum update -y
   

2. 安裝必要工具：安裝編譯工具及網絡工具

   sudo yum install -y wget curl gcc-c++ make
   

二、安裝Node.js與npm

Swagger UI依賴Node.js環境，需先安裝對應版本（推薦Node.js 12.x及以上）：

# 添加NodeSource源（以12.x為例）
curl -sL https://rpm.nodesource.com/setup_12.x | sudo bash -

# 安裝Node.js及npm
sudo yum install -y nodejs

# 驗證安裝
node -v  # 應輸出v12.x.x及以上版本
npm -v   # 應輸出6.x.x及以上版本

三、部署Swagger UI

方式1：快速啟動Swagger UI（單節點模式）

1. 下載Swagger UI：從GitHub獲取最新穩定版

   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 --strip-components=1
   

2. 啟動靜態服務：使用http-server快速啟動Swagger UI

   npm install -g http-server
   http-server -p 8080 ./dist
   

3. 訪問Swagger UI：在瀏覽器中輸入http://<服務器IP>:8080，即可看到Swagger UI界面。

方式2：集成Express的長期運行方案

若需自定義接口文檔路徑或添加認證等功能，可通過Express框架部署：

1. 創建項目目錄：

   mkdir -p /opt/swagger/{public,server}
   cd /opt/swagger/server
   

2. 初始化項目并安裝依賴：

   npm init -y
   npm install express --save
   

3. 配置靜態資源與接口：創建index.js文件，內容如下：

   const express = require('express');
   const app = express();
   const path = require('path');
   
   // 指向Swagger UI的靜態文件目錄
   app.use('/static', express.static(path.join(__dirname, '../public')));
   
   // 可選：自定義API文檔路徑（需將接口文檔放入public目錄）
   // app.get('/api-docs', (req, res) => {
   //   res.sendFile(path.join(__dirname, '../public/your-api-docs.json'));
   // });
   
   // 啟動服務
   app.listen(3000, () => {
     console.log('Swagger UI運行于 http://localhost:3000/static/index.html');
   });
   

4. 啟動服務：

   node index.js
   

5. 訪問Swagger UI：在瀏覽器中輸入http://<服務器IP>:3000/static/index.html。

四、配置自定義API文檔

1. 編寫接口文檔：使用Swagger Editor（可選）編寫API描述文件（支持JSON/YAML格式），保存為api-docs.json（或api-docs.yaml）。
2. 上傳文檔：將文檔復制到Swagger UI的public目錄（如/opt/swagger/public）。
3. 修改索引文件：編輯/opt/swagger/public/index.html，找到以下代碼：

   const ui = SwaggerUIBundle({
     url: "https://petstore.swagger.io/v2/swagger.json", // 替換為你的文檔路徑
     // ...
   });
   

   將url值改為本地文檔路徑，例如：

   url: "/static/api-docs.json"
   

4. 重啟服務：若使用Express方案，需重啟node index.js使配置生效。

五、生產環境優化建議

1. 啟用HTTPS：使用Let’s Encrypt免費證書，通過Nginx或Apache反向隧道配置HTTPS，避免數據傳輸泄露。
2. 配置防火墻：開放必要端口（如80/443或自定義端口），關閉無關端口：

   sudo firewall-cmd --permanent --add-port=80/tcp
   sudo firewall-cmd --permanent --add-port=443/tcp
   sudo firewall-cmd --reload
   

3. 權限管理：避免使用root用戶運行服務，建議創建專用用戶（如swagger）并賦予權限。
4. 持久化存儲：將Swagger UI目錄掛載至云存儲（如OSS），防止數據丟失。

通過以上步驟，即可在CentOS系統上完成Swagger UI的部署，并通過瀏覽器訪問交互式API文檔。如需進一步定制（如添加認證、修改主題），可參考Swagger UI官方文檔進行調整。