跳至內容

路徑與操作

在 OpenAPI 術語中，路徑 是端點（資源），例如 /users 或 /reports/summary/，您的 API 會公開這些端點，而操作 則是用於操作這些路徑的 HTTP 方法，例如 GET、POST 或 DELETE。

路徑

API 路徑和操作在 API 規格的全域 paths 區段中定義。

1
paths:
2
  /ping: ...
3
  /users: ...
4
  /users/{id}: ...

所有路徑都相對於 API 伺服器 URL。完整的請求 URL 結構為 <server-url>/path。全域 servers 也可以在路徑層級或操作層級覆寫（詳細資訊請參閱下方）。路徑可以有選用的簡短 summary 和較長的 description，以用於文件用途。此資訊應與此路徑中的所有操作相關。description 可以是多行，並支援 Markdown (CommonMark) 以呈現豐富文字。

1
paths:
2
  /users/{id}:
3
    summary: Represents a user
4
    description: >
5
      This resource represents an individual user in the system.
6
      Each user is identified by a numeric `id`.
7


8
    get: ...
9
    patch: ...
10
    delete: ...

路徑範本

您可以使用大括號 {} 將 URL 的部分標記為路徑參數

1
/users/{id}
2
/organizations/{orgId}/members/{memberId}
3
/report.{format}

API 用戶端在發出 API 呼叫時需要提供適當的參數值，例如 /users/5 或 /users/12。

操作

針對每個路徑，您可以定義可用於存取該路徑的操作（HTTP 方法）。OpenAPI 3.0 支援 get、post、put、patch、delete、head、options 和 trace。單一路徑可以支援多個操作，例如 GET /users 以取得使用者清單，而 POST /users 則新增使用者。OpenAPI 將路徑和 HTTP 方法的組合定義為唯一的操作。這表示不允許對同一路徑使用兩個 GET 或兩個 POST 方法，即使它們具有不同的參數（參數對唯一性沒有影響）。以下是操作的最小範例

1
paths:
2
  /ping:
3
    get:
4
      responses:
5
        "200":
6
          description: OK

以下是更詳細的範例，包含參數和回應結構描述

1
paths:
2
  /users/{id}:
3
    get:
4
      tags:
5
        - Users
6
      summary: Gets a user by ID.
7
      description: >
8
        A detailed description of the operation.
9
        Use markdown for rich text representation,
10
        such as **bold**, *italic*, and [links](https://swagger.dev.org.tw).
11
      operationId: getUserById
12
      parameters:
13
        - name: id
14
          in: path
15
          description: User ID
16
          required: true
17
          schema:
18
            type: integer
19
            format: int64
20
      responses:
21
        "200":
22
          description: Successful operation
23
          content:
24
            application/json:
25
              schema:
26
                $ref: "#/components/schemas/User"
27
      externalDocs:
28
        description: Learn more about user operations provided by this API.
29
        url: http://api.example.com/docs/user-operations/
30


31
components:
32
  schemas:
33
    User:
34
      type: object
35
      properties:
36
        id:
37
          type: integer
38
          format: int64
39
        name:
40
          type: string
41
      required:
42
        - id
43
        - name

操作也支援一些選用元素，以用於文件用途

  • 簡短的 summary 和較長的 description，說明操作的功能。description 可以是多行，並支援 Markdown (CommonMark) 以呈現豐富文字。
  • tags – 用於依資源或任何其他限定詞，以邏輯方式分組操作。請參閱使用標籤分組操作。
  • externalDocs – 用於參考包含其他文件的外部資源。

操作參數

OpenAPI 3.0 支援透過路徑、查詢字串、標頭和 Cookie 傳遞的操作參數。您也可以為將資料傳輸到伺服器的操作定義請求主體，例如 POST、PUT 和 PATCH。如需詳細資訊，請參閱描述參數和描述請求主體。

路徑中的查詢字串

查詢字串參數不得包含在路徑中。它們應改為定義為查詢參數。

不正確

1
paths:
2
  /users?role={role}:

正確

1
paths:
2
  /users:
3
    get:
4
      parameters:
5
        - in: query
6
          name: role
7
          schema:
8
            type: string
9
            enum: [user, poweruser, admin]
10
          required: true

這也表示不可能有多個僅在查詢字串中不同的路徑，例如

1
GET /users?firstName=value&lastName=value
2
GET /users?role=value

這是因為 OpenAPI 將路徑和 HTTP 方法的組合視為唯一的操作，而額外參數不會使操作變成唯一。您應該改為使用唯一的路徑，例如

1
GET /users/findByName?firstName=value&lastName=value
2
GET /users/findByRole?role=value

operationId

operationId 是選用的唯一字串，用於識別操作。如果提供，這些 ID 在您的 API 中描述的所有操作中必須是唯一的。

1
/users:
2
  get:
3
    operationId: getUsers
4
    summary: Gets all users
5
    ...
6
  post:
7
    operationId: addUser
8
    summary: Adds a new user
9
    ...
10
/user/{id}:
11
  get:
12
    operationId: getUserById
13
    summary: Gets a user by user ID
14
    ...

operationId 的一些常見使用案例如下

  • 某些程式碼產生器會使用此值來命名程式碼中對應的方法。
  • 連結可以透過 operationId 參考連結的操作。

已棄用的操作

您可以將特定操作標記為 deprecated，以表示它們應逐步淘汰

1
/pet/findByTags:
2
  get:
3
    deprecated: true

工具可能會以特定方式處理已棄用的操作。例如，Swagger UI 會以不同的樣式顯示它們

Deprecated operation in Swagger UI

覆寫全域伺服器

全域 servers 陣列可以在路徑層級或操作層級覆寫。如果某些端點使用與 API 其餘部分不同的伺服器或基礎路徑，這會很有用。常見範例如下

  • 用於檔案上傳和下載操作的不同基礎 URL。

  • 已棄用但仍可運作的端點。

    servers

1
paths:
2
  /files:
3
    description: File upload and download operations
4
    servers:
5
      - url: https://files.example.com
6
        description: Override base path for all operations with the /files path
7
    ...
8


9
/ping:
10
    get:
11
      servers:
12
        - url: https://echo.example.com
13
          description: Override base path for the GET /ping operation

沒有找到您要尋找的內容嗎？向社群提問 發現錯誤？讓我們知道

Swagger 開源
Swagger
專業工具
資源