前言

在前幾天，我們學了 API 的基本概念、請求與回應，還有常見的資料格式。今天要來看看一個非常實用的工具 —— Swagger，它能幫我們自動產生 API 文件，甚至可以直接在文件上測試 API。

為甚麼需要API文件?

想像一下：

• 你開發了一組 API，但團隊成員不知道怎麼用。
• 其他人想串接 API，卻不知道有哪些 Endpoint、需要哪些參數。

這時候，清楚的 API 文件就非常重要。它能解決：

• API 的 使用方式說明
• 輸入與輸出格式
• 範例測試

Swagger 是什麼？

Swagger 是一個開源工具，用來 設計、建構、記錄、測試 API。
它的核心是 OpenAPI 規範（OpenAPI Specification, OAS）。

Swagger UI

如果你在專案中安裝 ** Swagger UI**，就能看到一個漂亮的網頁文件，像這樣：

• /todos → 按一下「Try it out」就能直接測試 API
• Response 範例會自動顯示
  這比自己寫 Word 文件或 README 更方便，也不容易過時。

常見應用

• 後端工程師 ：自動生成 API 文件
• 前端工程師 ：直接在文件頁面測試 API
• 測試工程師 ：更快理解 API 行為
• 外部開發者 ：快速上手 API 串接

小結

• API 文件對團隊溝通非常重要
• Swagger 能幫我們快速建立 API 文件，甚至直接測試
• 未來學習 FastAPI 時，也會用到 OpenAPI 規範（內建支援 Swagger UI！）