如何使用CentOS上的Swagger進行測試

一、CentOS上Swagger測試前置準備

在CentOS系統上進行Swagger測試前，需完成以下環境配置：

1. 更新系統：運行sudo yum update -y確保系統軟件包為最新版本。
2. 安裝Node.js和npm：Swagger依賴Node.js環境，通過以下命令安裝：

   sudo yum install gcc-c++ make -y
   curl -sL https://rpm.nodesource.com/setup_14.x | bash -  # 使用Node.js 14.x版本（兼容性更好）
   sudo yum install nodejs -y
   # 驗證安裝
   node -v  # 應輸出Node.js版本（如v14.xx.xx）
   npm -v   # 應輸出npm版本（如6.xx.xx）
   

3. 安裝Docker（可選，推薦用于快速部署）：若需通過Docker運行Swagger UI，需先安裝Docker：

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

二、Swagger組件部署（兩種方式）

1. 通過Docker快速部署（推薦）

Docker可簡化Swagger UI的部署流程，無需手動配置依賴：

• 拉取Swagger UI鏡像：

  docker pull swaggerapi/swagger-ui:v4.15.5  # 拉取最新穩定版鏡像
  

• 運行Swagger UI容器：

  docker run -d -p 8080:8080 -e SWAGGER_FILE=/app/swagger.yaml -v /path/to/your/swagger.yaml:/app/swagger.yaml swaggerapi/swagger-ui:v4.15.5
  

  其中：
  • -p 8080:8080：將容器的8080端口映射到主機的8080端口；
  • -e SWAGGER_FILE：指定Swagger文檔路徑（需替換為你的swagger.yaml/swagger.json文件路徑）；
  • -v：將主機上的Swagger文檔掛載到容器內。
• 訪問Swagger UI：在瀏覽器中輸入http://<CentOS服務器IP>:8080，即可看到Swagger UI界面。

2. 手動部署（適用于自定義配置）

若需更多定制化功能，可手動下載并配置Swagger Editor和Swagger UI：

• 下載Swagger組件：

  mkdir -p /opt/swagger
  cd /opt/swagger
  wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz
  wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz
  tar -xzf v3.14.0.tar.gz
  tar -xzf v3.34.0.tar.gz
  

• 啟動Swagger Editor：

  cd /opt/swagger/swagger-editor-3.14.0
  npm install -g http-server
  http-server -p 8081  # 啟動Editor服務，訪問http://<IP>:8081編寫API文檔
  

• 啟動Swagger UI：

  cd /opt/swagger/swagger-ui-3.34.0
  npm init -y
  npm install express --save
  mkdir public
  cp -r dist/* public/  # 復制Swagger UI靜態文件到public目錄
  # 編輯index.js（配置API文檔路徑）
  vi index.js
  

  在index.js中添加以下內容：

  const express = require('express');
  const app = express();
  app.use('/static', express.static('public'));
  app.get('/', (req, res) => {
    res.sendFile(__dirname + '/public/index.html');
  });
  app.listen(3000, () => console.log('Swagger UI running on port 3000'));
  

  啟動服務：node index.js，訪問http://<IP>:3000即可看到Swagger UI界面。

三、編寫/導入Swagger文檔

1. 編寫Swagger文檔：
   使用Swagger Editor（http://<IP>:8081）編寫API文檔，支持YAML或JSON格式。例如，一個簡單的swagger.yaml內容如下：

   openapi: 3.0.0
   info:
     title: Test API
     version: 1.0.0
   paths:
     /user/query:
       get:
         summary: Query user information
         parameters:
           - name: userId
             in: query
             required: true
             schema:
               type: integer
         responses:
           '200':
             description: Successful response
             content:
               application/json:
                 schema:
                   type: object
                   properties:
                     id:
                       type: integer
                     name:
                       type: string
   

2. 導入文檔：
   • 若使用Docker部署，在運行容器時通過-e SWAGGER_FILE指定文檔路徑；
   • 若手動部署，將文檔復制到Swagger UI的public目錄（如/opt/swagger/public），并修改public/index.html中的SWAGGER_URL變量，指向本地文檔（如http://<IP>:3000/static/your-swagger.yaml）。

四、使用Swagger UI進行接口測試

1. 訪問Swagger UI：打開瀏覽器，輸入http://<CentOS服務器IP>:8080（Docker部署）或http://<IP>:3000（手動部署），進入Swagger UI界面。
2. 查看接口列表：左側面板會顯示Swagger文檔中的所有接口（如/user/query）。
3. 測試接口：
   • 點擊目標接口（如/user/query），右側面板會顯示接口詳情（參數、請求方式、響應格式）；
   • 點擊Try it out按鈕，輸入必填參數（如userId: 1）；
   • 再次點擊Execute，Swagger UI會自動發送HTTP請求到后端服務；
   • 查看Response區域，顯示后端返回的結果（如{"id":1,"name":"John"}）。

五、補充：使用curl命令測試接口

若需在終端中測試接口，可使用curl命令（無需依賴Swagger UI）：

• GET請求（參數在URL中）：

  curl "http://<服務器IP>:<接口端口>/user/query?userId=1"
  

• POST請求（參數在Body中，表單格式）：

  curl -X POST "http://<服務器IP>:<接口端口>/factory/insert" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "factoryName=TestFactory&no=123&remark=TestRemark"
  

• POST請求（參數在Body中，JSON格式）：

  curl -X POST "http://<服務器IP>:<接口端口>/material/selectAll" \
  -H "Content-Type: application/json" \
  -d '{"factory":"TestFactory","materialName":"TestMaterial","offset":0,"page":1}'
  

• 文件上傳請求：

  curl -X POST "http://<服務器IP>:<接口端口>/api/all/order/money" \
  -F "file=@/path/to/local/file.xlsx" \
  -F "startTime=2025-01-01" \
  -F "endTime=2025-06-30"
  

注意事項

• 生產環境安全：測試完成后，建議禁用Swagger UI（如刪除容器或停止服務），避免接口文檔泄露；
• 防火墻設置：確保CentOS防火墻開放了Swagger UI的端口（如8080、3000），可通過firewall-cmd --add-port=8080/tcp --permanent和firewall-cmd --reload命令配置；
• 文檔更新：修改Swagger文檔后，需重啟Swagger UI服務（手動部署）或重新掛載文檔（Docker部署），確保界面顯示最新內容。