在 Swagger 中管理 API 版本可以幫助你清楚地維護多個版本的 API，同時為用戶提供明確的使用指引。

1. 使用 URL 路徑中的版本號

在 URL 中明確指定版本號是一種非常常見的做法。通常，你會在 API 路徑中包含版本號，比如 v1、v2 等。

範例：

• https://api.example.com/v1/users
• https://api.example.com/v2/users

在 Swagger 中，你可以使用 basePath 或 servers 屬性指定 API 的版本號：

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1

透過這種方式，Swagger 文件將自動關聯到指定的 API 版本。

2. 使用請求標頭管理版本

你可以使用 HTTP 請求標頭來傳遞版本資訊，例如 Accept 或自訂的 X-Version 請求標頭。

範例：

• GET /users
• Accept: application/vnd.example.v1+json（透過 Accept 標頭指定版本）
• X-Version: 1（使用自訂標頭）

在 Swagger 中，可以透過 parameters 欄位定義這些標頭資訊：

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get Users
      parameters:
        - in: header
          name: X-Version
          schema:
            type: string
          required: true
          description: API Version

3. 使用查詢參數管理版本

透過查詢參數傳遞版本號也是一種常見的方式，例如 ?version=1。

範例：

• GET /users?version=1

你可以在 Swagger 中透過 parameters 欄位定義查詢參數：

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get Users
      parameters:
        - in: query
          name: version
          schema:
            type: string
          required: true
          description: API Version

4. 多個 Swagger 文件

你還可以為每個 API 版本生成單獨的 Swagger 文件，並為每個文件配置不同的版本資訊。這樣做可以讓每個 API 版本都有獨立的文件。

範例：

• swagger-v1.yaml（API V1 文件）
• swagger-v2.yaml（API V2 文件）

每個文件中的 info 欄位下的 version 會指向不同的 API 版本。

5. 使用 tags 區分版本

如果你希望在同一個 Swagger 文件中維護多個版本的 API，可以使用 tags 來區分 API 版本，並在描述中明確標註。

範例：

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - v1
      summary: Get Users (v1)
    post:
      tags:
        - v2
      summary: Create Users (v2)

在這種情況下，API 的不同版本會根據 tags 標籤在 Swagger UI 中分組顯示。

總結

• 使用 URL 路徑可以直接將版本號暴露給用戶，是最常見的做法。
• 透過請求標頭和查詢參數可以靈活地傳遞版本資訊。
• 如果 API 變化較大，可以生成多個 Swagger 文件來獨立管理各個版本。
• tags 可以幫助你在同一個 Swagger 文件中區分不同的版本。

選擇合適的版本管理方式取決於你的 API 設計和使用場景。