基本結構

Swagger 定義可以使用 JSON 或 YAML 撰寫。在本指南中，我們僅使用 YAML 範例，但 JSON 也同樣適用。以 YAML 撰寫的 Swagger 規格範例如下

1
swagger: "2.0"
2
info:
3
  title: Sample API
4
  description: API description in Markdown.
5
  version: 1.0.0
6

7
host: api.example.com
8
basePath: /v1
9
schemes:
10
  - https
11

12
paths:
13
  /users:
14
    get:
15
      summary: Returns a list of users.
16
      description: Optional extended description in Markdown.
17
      produces:
18
        - application/json
19
      responses:
20
        200:
21
          description: OK

中繼資料

每個 Swagger 規格都以 Swagger 版本開始，2.0 是最新版本。Swagger 版本定義 API 規格的整體結構 – 您可以記錄什麼以及如何記錄它。

1
swagger: "2.0"

然後，您需要指定 API info – title、description（選用）、version（API 版本，而非檔案修訂或 Swagger 版本）。

1
info:
2
  title: Sample API
3
  description: API description in Markdown.
4
  version: 1.0.0

version 可以是隨機字串。您可以使用 major.minor.patch（如語意化版本控制），或任意格式，例如 1.0-beta 或 2016.11.15。description 可以是多行，並支援 GitHub Flavored Markdown 以進行豐富的文字表示。info 也支援其他欄位，以提供聯絡資訊、授權和其他詳細資料。參考： Info 物件。

基本 URL

所有 API 呼叫的基本 URL 是使用 schemes、host 和 basePath 定義的

1
host: api.example.com
2
basePath: /v1
3
schemes:
4
  - https

所有 API 路徑都是相對於基本 URL。例如，/users 實際上表示 https://api.example.com/v1/users。更多資訊： API 主機和基本 URL。

Consumes、Produces

consumes 和 produces 區段定義 API 支援的 MIME 類型。根層級的定義可以在個別操作中覆寫。

1
consumes:
2
  - application/json
3
  - application/xml
4
produces:
5
  - application/json
6
  - application/xml

更多資訊： MIME 類型。

路徑

paths 區段定義 API 中的個別端點（路徑）和這些端點支援的 HTTP 方法（操作）。例如，GET /users 可以描述為

1
paths:
2
  /users:
3
    get:
4
      summary: Returns a list of users.
5
      description: Optional extended description in Markdown.
6
      produces:
7
        - application/json
8
      responses:
9
        200:
10
          description: OK

更多資訊： 路徑和操作。

參數

操作可以有參數，這些參數可以透過 URL 路徑 (/users/{userId})、查詢字串 (/users?role=admin)、標頭 (X-CustomHeader: Value) 和請求主體傳遞。您可以定義參數類型、格式、它們是必要還是選用，以及其他詳細資料

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: Parameter description in Markdown.
12
      responses:
13
        200:
14
          description: OK

更多資訊： 描述參數。

回應

對於每個操作，您可以定義可能的狀態碼，例如 200 OK 或 404 Not Found，以及回應主體的 schema。結構描述可以內嵌定義，也可以透過 $ref 從外部定義參照。您也可以為不同的內容類型提供範例回應。

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: The ID of the user to return.
12
      responses:
13
        200:
14
          description: A User object.
15
          schema:
16
            type: object
17
            properties:
18
              id:
19
                type: integer
20
                example: 4
21
              name:
22
                type: string
23
                example: Arthur Dent
24
        400:
25
          description: The specified user ID is invalid (e.g. not a number).
26
        404:
27
          description: A user with the specified ID was not found.
28
        default:
29
          description: Unexpected error

更多資訊： 描述回應。

輸入和輸出模型

全域 definitions 區段可讓您定義 API 中使用的常見資料結構。每當需要 schema 時，都可透過 $ref 參照它們 – 無論是針對請求主體還是回應主體。例如，此 JSON 物件

1
{
2
  "id": 4,
3
  "name": "Arthur Dent"
4
}

可以表示為

1
definitions:
2
  User:
3
    properties:
4
      id:
5
        type: integer
6
      name:
7
        type: string
8
    # Both properties are required
9
    required:
10
      - id
11
      - name

然後在請求主體結構描述和回應主體結構描述中參照如下

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
      responses:
11
        200:
12
          description: OK
13
          schema:
14
            $ref: "#/definitions/User"
15
  /users:
16
    post:
17
      summary: Creates a new user.
18
      parameters:
19
        - in: body
20
          name: user
21
          schema:
22
            $ref: "#/definitions/User"
23
      responses:
24
        200:
25
          description: OK

驗證

securityDefinitions 和 security 關鍵字用於描述 API 中使用的驗證方法。

1
securityDefinitions:
2
  BasicAuth:
3
    type: basic
4

5
security:
6
  - BasicAuth: []

支援的驗證方法如下

基本驗證
API 金鑰（作為標頭或查詢參數）
OAuth 2 常見流程（隱含、密碼、應用程式和存取碼）

更多資訊： 驗證。

找不到您要的資訊嗎？向社群提問
發現錯誤？讓我們知道