在 API 開發過程中，測試是必不可少的一環，而選擇合適的測試工具能夠大大提高測試的效率和準確性。Swagger 和 Postman 是兩個常見且強大的 API 測試工具，分別擁有各自的特點和優勢，能夠幫助開發者快速測試和驗證 API。今天我們將探討這兩個工具，並介紹它們的主要功能與使用情境。

Swagger 是什麼？

Swagger 是一個開源的 API 文檔生成工具集，它不僅能夠幫助開發者自動生成 API 文件，還能夠提供一個互動界面來測試 API。Swagger 的最大優勢是與代碼緊密結合，能夠通過注釋自動生成 API 文檔，並且提供即時測試的功能。

Swagger 的主要功能

1. 自動生成 API 文件

   Swagger 能夠根據程式碼中的注釋或標註，動態生成 API 文件，這樣開發者可以輕鬆地為每一個 API 生成清晰的說明文件，並且不需要手動撰寫文檔。

2. 互動式 API 測試界面

   透過 Swagger 的 UI 界面，開發者可以直接測試 API。Swagger 提供了基於網頁的測試功能，開發者可以直接通過瀏覽器發送 API 請求，並查看返回結果。這對於快速驗證 API 功能非常有幫助。

3. 提供 API 說明與示例

   每個 API 的說明都可以透過 Swagger 自動生成，並且包含輸入參數、返回值、HTTP 方法等詳細資訊。這讓 API 使用者能夠清晰地了解如何使用 API，並且能夠依據範例進行調用。

Open API 文件

OpenAPI 文件是一種標準化的格式，用於描述 RESTful API 的結構和行為。它使得開發者能夠以統一的方式描述 API 的端點、HTTP 方法、請求參數、響應格式、驗證機制等細節。OpenAPI 以前稱為 Swagger 規範，是一種開源格式，旨在幫助開發者定義、生成和消費 API。

OpenAPI 文檔可以用 JSON 或 YAML 格式編寫，常見於現代 API 開發中。這些文檔不僅能夠作為 API 的說明書，還能被自動生成工具（如 Swagger UI 或 Postman）用於創建可互動的測試接口。這樣的文檔能極大地促進開發人員之間的協作，並幫助第三方使用者理解和調用 API。

在 OpenAPI JSON 格式中，文件的結構由以下幾個部分組成：

1. openapi: 定義使用的 OpenAPI 規範版本，例如 "openapi": "3.0.0"。
2. info: 提供有關 API 的基本信息，如 API 名稱、版本、描述等。
3. servers: 列出 API 部署的服務器地址。
4. paths: 定義 API 的各個端點及其支持的 HTTP 方法（GET、POST、PUT、DELETE 等），以及請求和回應的格式。
5. components: 包含 API 的可重用部分，如數據模式（schemas）、安全機制（securitySchemes）等。
6. security: 說明 API 的認證和授權方式。
7. tags: 用於對 API 端點進行分組，以便更清晰地展示和組織 API。

例如，以下是一個簡單的 OpenAPI JSON 範例：

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0",
    "description": "This is a sample API"
  },
  "servers": [
    {
      "url": "<https://api.example.com/v1>"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "Get all users",
        "responses": {
          "200": {
            "description": "A list of users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

這個文件定義了一個簡單的 API，其中 /users 端點支持 GET 請求，並返回用戶列表。

在前幾天，我們有實際開發一個簡單的.Net Core Web API ，並且最後使用Swagger執行！

拿這個API做舉例，

一樣執行後，可以在專案名成下面的網址Click後

就會開啟Open API 的文件了ㄌ

而在文章最下面可以看到components的資訊

使用 Swagger 的優缺點

優點：

• 自動生成文件，減少手動撰寫文檔的工作。
• 提供即時測試 API 的能力。
• 對 API 的結構與參數有詳細的說明，對 API 使用者友好。

缺點：

• 主要針對 REST API，對其他 API 架構（如 gRPC）的支持有限。
• 需要開發者在程式碼中添加足夠的注釋與描述，否則生成的文檔可能不夠詳細。

Postman 是什麼？

Postman 是一款功能強大的 API 測試工具，具有友好的用戶界面，能夠幫助開發者輕鬆編寫和執行 API 測試。與 Swagger 不同的是，Postman 更側重於 API 測試和調試，而不僅僅是 API 文件的生成。Postman 支持多種 API 格式，如 REST、GraphQL、SOAP 等，並且可以進行複雜的測試自動化。可以參考 Postman中文文檔。

Postman 的主要功能

1. 簡單的請求組織與管理

   Postman 允許開發者創建一系列的 API 請求，並將這些請求組織在「集合」（Collection）中，這對於進行多步驟 API 測試和場景測試非常有幫助。

2. 強大的測試腳本功能

   Postman 支持使用 JavaScript 編寫測試腳本，這些腳本可以在發送 API 請求之前或之後執行，用於驗證 API 回應是否符合預期。這使得 Postman 不僅僅是一個簡單的 API 測試工具，更是一個強大的測試自動化工具。

3. 環境變數管理

   Postman 提供環境變數的管理功能，這讓開發者可以在不同的環境中快速切換 API 測試。例如，可以為開發環境、測試環境和生產環境設置不同的 API URL 或憑證。

4. API 測試報告與監控

   Postman 允許開發者將 API 測試結果匯總成報告，並且可以設置自動化的 API 測試監控，定期驗證 API 是否運行正常，這對於大型系統的健康檢查非常有幫助。

簡單的 Postman 使用範例

一樣使用前幾天開發的簡易產品API來做測試～

首先開啟下載好的Postman，首先要先建立Workspace，按照下圖的流程做～

再來我們要匯入我們的OpenAPI文件，在上一部建立好的Workspace，點選Import，並且將上面我們的產品API Open API Json 開個檔案存起來後匯入，選擇Open API 這個Type。

匯入後，就可以看到Postman幫我們建立好完整的API工作區塊，開啟後要先找到你專案的Variables來設定baseUrl

設定完就可以執行試試看啦～

一樣可以看到執行的狀況，也可以看到執行的秒數等等資訊，比起Swagger功能性更完整更好用，

那再來試試看建立產品的API，可以看到系統直接幫我的Http Body 建立好一組JSON格式的Request，並且參數型別也都附上了，方便做測試～

可以看到執行完的結果，回傳201Created 成功建立，建立成功的回傳物件。

這樣基本的Postman使用就完成啦～

等後面如何保護API的章節時，我會在花一點篇幅說明Swagger不能用於header帶驗證資訊的缺點，並且該怎麼使用Postman完成驗證等等，等之後的篇幅再繼續～

至於Postman自動化功能與測試腳本，等到後面有空的話我再補充，尤其是自動化對於針對一些API站台取權限等等的非常好用！

使用 Postman 的優缺點

優點：

• 支持多種 API 格式，適用性強。
• 提供強大的測試腳本與自動化功能，適合複雜測試場景。
• 界面簡潔，操作方便，適合多個團隊成員協作。

缺點：

• 與代碼沒有直接關聯，需要手動管理測試請求與集合。
• 測試腳本的編寫需要一定的 JavaScript 技能，對新手來說可能有一定的學習曲線。

Swagger 與 Postman 的比較

每日小結

無論是 Swagger 還是 Postman，都在 API 測試領域中扮演著重要角色。Swagger 更側重於自動生成 API 文檔和快速測試 API，適合開發過程中的初期測試。而 Postman 則提供了強大的測試自動化和腳本功能，更適合進行詳細測試和複雜場景下的驗證。

在實際開發中，開發者可以靈活選擇 Swagger 和 Postman，根據需求進行測試與文檔管理。

如果你正在開發一個 REST API，並且需要快速生成 API 文檔、進行即時測試，Swagger 是非常方便的工具。它能夠自動生成文件，並且提供互動式的測試界面，讓 API 使用者能夠快速上手。而在需要進行多步驟測試、自動化測試，或者需要處理更複雜的測試場景時，Postman 是更為合適的選擇。它支持各種 API 格式，並且可以透過編寫腳本來自動化測試流程，還能生成測試報告以便團隊協作。

實際上，在開發過程中，許多團隊會將兩者結合使用。在開發初期，通過 Swagger 生成 API 文檔並進行快速測試，隨著開發進度，逐步在 Postman 中創建完整的測試集合，用於驗證 API 的穩定性和正確性，並且確保每次系統更新後都能及時發現潛在的問題。