如何使用 Swagger 編寫 API 文檔
1. 選擇工具：
可以選擇在 Swagger Editor（線上版本）或本地的 YAML/JSON 編輯器 中撰寫 Swagger 文件。最推薦的是使用線上的 Swagger Editor，方便即時編輯和查看效果。
https://editor.swagger.io/

2. 撰寫OpenAPI規範：
OpenAPI 是 Swagger 文件的核心，它能用 YAML 或 JSON 格式撰寫。我們以 YAML 格式為例，展示如何撰寫一個簡單的 API 文檔。

首先，從文件的 openapi 版本與基本資訊（info 區域）開始撰寫。以下是範例：

**3. 定義 API 路徑： **
在 paths 區塊中定義每個 API 的路徑。這裡我們定義了一個用來獲取用戶列表的 API 路徑 /users。

這段代碼的意思是：當用戶訪問 GET /users 路徑時，會返回一個用戶列表，包含 id 和 name 兩個欄位。

4. 添加請求參數與回應結構：
如果 API 有需要的請求參數（例如 URL 參數、查詢參數）或具體的回應結構，則需要在 parameters 和 responses 中詳細描述。

這裡定義了 /users/{userId} 路徑，並在 URL 中接受一個 userId 參數來查詢具體用戶。

如何生成可視化的 API 文檔
使用 Swagger UI：
最簡單的方式就是將你的 OpenAPI 文件加載到 Swagger UI，它會自動將 YAML 文件轉換成可視化界面。

• 如果你使用 Swagger Editor，只需在編輯區完成 API 定義後，右側就會即時生成一個可視化的 API 文檔，方便你進行測試。
• 你也可以下載 Swagger UI，並將你的 API 文檔與它整合，讓你的 API 文件展示給所有用戶。

運行本地服務器：
將 OpenAPI 文件部署到本地或雲端服務器，並使用 Swagger UI 展示文檔。將 openapi.yaml 文件與 Swagger UI 的靜態資源一起運行，你就能得到一個可互動的 API 文檔頁面。

範例:
假設你已經完成了上面的 YAML 文件編寫，你只需將這個文件導入 Swagger UI，就能立刻生成一個可視化的 API 文檔，並且可以點擊界面上的按鈕來測試 API

在 Swagger UI 中，這段文件會展示為一個可點擊的接口，能直接測試回應「Hello, world!」。