如何在Linux上使用Swagger進行API接口調試

一、準備工作：安裝基礎工具

在Linux上使用Swagger進行API調試前，需先安裝Node.js（提供npm包管理器）和Docker（可選，用于快速部署Swagger Editor/UI）。

• 安裝Node.js和npm（適用于Debian/Ubuntu系統）：

  sudo apt update && sudo apt install -y nodejs npm
  

• 安裝Docker（可選，用于容器化部署）：
  參考Docker官方文檔安裝Docker Engine，確保docker命令可用。

二、安裝Swagger工具

1. 方式一：通過npm安裝（適合開發環境）

• 安裝Swagger Editor（在線編輯API規范）：

  sudo npm install -g swagger-editor
  

• 安裝Swagger UI（可視化調試界面）：

  sudo npm install -g swagger-ui
  

• 啟動服務：
  • Swagger Editor：運行swagger-editor，默認訪問http://localhost:9000；
  • Swagger UI：運行swagger-ui，默認訪問http://localhost:8080。

2. 方式二：通過Docker安裝（推薦，避免環境沖突）

• 拉取Swagger Editor鏡像：

  docker pull swaggerapi/swagger-editor:v4.6.0
  

• 運行Editor容器（映射端口8080）：

  docker run -d -p 38080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0
  

• 拉取Swagger UI鏡像：

  docker pull swaggerapi/swagger-ui:v4.15.5
  

• 運行UI容器（映射端口38081）：

  docker run -d -p 38081:8080 --name swagger-ui swaggerapi/swagger-ui:v4.15.5
  

• 訪問地址：
  • Swagger Editor：http://<Linux服務器IP>:38080；
  • Swagger UI：http://<Linux服務器IP>:38081。

三、配置API文檔

1. 編寫Swagger規范文件

創建swagger.yaml（或swagger.json）文件，定義API的基本信息、路徑、參數、響應等。示例如下：

swagger: '2.0'
info:
  title: Linux API調試示例
  version: 1.0.0
  description: 用于演示Linux環境下Swagger調試的API
basePath: /api/v1
schemes:
  - http
paths:
  /user/{id}:
    get:
      summary: 根據用戶ID獲取用戶信息
      description: 返回指定ID的用戶詳情
      parameters:
        - name: id
          in: path
          required: true
          type: integer
          description: 用戶唯一標識
      responses:
        '200':
          description: 成功獲取用戶信息
          schema:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
        '404':
          description: 用戶不存在

2. 集成到應用（可選，適合后端項目）

若使用Spring Boot框架，可通過依賴和配置自動生成Swagger文檔：

• 添加Maven依賴（pom.xml）：

  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
  </dependency>
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
  </dependency>
  

• 配置Swagger（Java配置類）：

  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  import springfox.documentation.builders.PathSelectors;
  import springfox.documentation.builders.RequestHandlerSelectors;
  import springfox.documentation.spi.DocumentationType;
  import springfox.documentation.spring.web.plugins.Docket;
  
  @Configuration
  public class SwaggerConfig {
      @Bean
      public Docket api() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 替換為你的Controller包路徑
                  .paths(PathSelectors.any())
                  .build();
      }
  }
  

• 啟動應用：訪問http://<服務器IP>:8080/swagger-ui.html（Spring Boot默認端口）即可查看文檔。

四、啟動Swagger服務并調試

1. 使用Swagger Editor編輯規范

• 訪問http://localhost:9000（本地）或http://<服務器IP>:38080（遠程），在線編寫/修改swagger.yaml文件；
• 實時校驗YAML語法，確保API定義符合OpenAPI規范。

2. 使用Swagger UI調試接口

• 訪問http://localhost:8080（本地）或http://<服務器IP>:38081（遠程），加載swagger.yaml文件；
• 在界面上找到目標接口（如/user/{id}/get），填寫路徑參數（如id: 1）；
• 點擊Try it out按鈕，發送請求；
• 查看Response區域，獲取接口返回結果（如狀態碼、響應體）。

3. 使用curl命令輔助測試（可選）

若不想用Swagger UI，可通過curl命令直接測試接口：

• GET請求（帶路徑參數）：

  curl -X GET "http://<服務器IP>:8080/api/v1/user/1"
  

• POST請求（帶JSON body）：

  curl -X POST "http://<服務器IP>:8080/api/v1/user/create" \
       -H "Content-Type: application/json" \
       -d '{"name": "John Doe", "age": 30}'
  

• POST請求（帶表單參數）：

  curl -X POST "http://<服務器IP>:8080/api/v1/user/login" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d "username=admin&password=123456"
  

• 上傳文件：

  curl -X POST "http://<服務器IP>:8080/api/v1/upload" \
       -F "file=@/path/to/local/file.txt" \
       -F "description=Test file"
  

注意事項

• 端口沖突：若端口已被占用，可通過-p參數修改映射端口（如docker run -d -p 4000:8080）；
• 跨域問題：若API與Swagger UI不在同一域名下，需在后端配置CORS（如Spring Boot添加@CrossOrigin注解）；
• 文檔更新：修改swagger.yaml后，需重啟Swagger UI服務（若通過swagger serve啟動）或刷新瀏覽器頁面。