Ubuntu上Swagger測試API的方法

Ubuntu上使用Swagger測試API的完整流程

1. 前置準備：安裝Node.js和npm

Swagger Editor和Swagger UI的安裝依賴Node.js環境，需先通過以下命令安裝：

sudo apt update
sudo apt install -y nodejs npm
# 驗證安裝
node -v  # 查看Node.js版本
npm -v   # 查看npm版本

2. 安裝Swagger Editor（可選，用于API文檔編輯與測試）

Swagger Editor提供可視化的API文檔編寫和實時測試功能，支持本地部署或Docker運行：

• 方式一：npm全局安裝+http-server啟動

  npm install -g swagger-editor
  npm install -g http-server
  # 進入Swagger Editor目錄并啟動
  cd /usr/local/lib/node_modules/swagger-editor
  http-server -p 8080
  

  訪問http://localhost:8080即可打開編輯器，默認加載Petstore示例API。

• 方式二：Docker運行

  docker pull swaggerapi/swagger-editor
  docker run -d -p 8888:8080 swaggerapi/swagger-editor
  

  訪問http://localhost:8888進入編輯器。

• 使用方法：
  點擊頂部菜單欄「File」→「Import」→「Open File」，選擇本地的swagger.yaml或swagger.json文件；編輯完成后，可直接在界面上點擊接口右側的「Try it out」按鈕，輸入參數并執行測試，查看響應結果。

3. 安裝Swagger UI（必用，用于API文檔可視化與測試）

Swagger UI是官方推薦的API文檔展示工具，支持在線測試接口，常見安裝方式如下：

• 方式一：npm全局安裝+Express集成

  npm install -g swagger-ui-express express
  mkdir swagger-ui-project && cd swagger-ui-project
  npm init -y
  # 創建server.js文件
  echo "const express = require('express');
  const swaggerUi = require('swagger-ui-express');
  const YAML = require('yamljs');
  const app = express();
  const swaggerDocument = YAML.load('./swagger.yaml'); // 加載本地API文檔
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
  const PORT = 3000;
  app.listen(PORT, () => console.log(\`Server running on http://localhost:\${PORT}\`));" > server.js
  # 啟動服務
  node server.js
  

  訪問http://localhost:3000/api-docs即可查看Swagger UI界面。

• 方式二：Docker運行

  docker pull swaggerapi/swagger-ui
  mkdir swagger-docs && cp /path/to/your/swagger.yaml swagger-docs/
  docker run -d -p 8080:8080 -e SWAGGER_JSON=/app/swagger.yaml -v $(pwd)/swagger-docs:/app swaggerapi/swagger-ui
  

  訪問http://localhost:8080，頁面會自動加載swagger.yaml文件。

• 方式三：直接下載源碼運行

  git clone https://github.com/swagger-api/swagger-ui.git
  cd swagger-ui
  npm install
  npm start
  

  訪問http://localhost:3000/swagger-ui/index.html，修改dist/index.html中的url字段（指向你的API文檔地址）即可自定義文檔來源。

4. 配置API文檔路徑

無論是Swagger Editor還是Swagger UI，都需要指定API文檔的位置：

• Swagger Editor：默認加載https://petstore.swagger.io/v2/swagger.json，可通過編輯index.html文件修改defaultDocument變量，指向本地或遠程文檔。
• Swagger UI：在啟動配置中指定文檔路徑（如上述Docker命令中的-e SWAGGER_JSON或server.js中的YAML.load('./swagger.yaml')）。

5. 使用Swagger UI測試API

啟動Swagger UI后，按照以下步驟進行接口測試：

1. 導入文檔：在頁面右上角點擊「Explore」按鈕，輸入API文檔的URL（如http://localhost:8080/v2/api-docs）或選擇本地swagger.yaml文件，點擊「Import」。
2. 選擇接口：在左側「Paths」面板中找到目標接口（如/users/get），點擊展開。
3. 輸入參數：根據接口定義填寫「Parameters」部分的參數（如查詢參數、路徑參數、請求體等），支持自動格式校驗。
4. 執行測試：點擊接口下方的「Try it out」按鈕，Swagger UI會自動發送HTTP請求到后端服務。
5. 查看結果：在「Responses」面板中查看響應狀態碼（如200表示成功）、響應頭和響應體（如JSON格式的數據）。

6. 常見問題解決

• 端口沖突：若默認端口（8080、3000）被占用，可在啟動命令中修改端口（如-p 8081:8080）。
• 文檔無法加載：檢查API文檔路徑是否正確，確保后端服務已啟動并暴露了Swagger文檔接口（如Spring Boot項目的/v2/api-docs）。
• 權限問題：若使用Docker運行，確保當前用戶對掛載目錄有讀寫權限（如chmod -R 777 swagger-docs）。

通過以上步驟，即可在Ubuntu系統上使用Swagger完成API文檔的編輯、展示和在線測試，提升開發效率。