列舉 (Enums)

您可以使用 enum 關鍵字來指定請求參數或模型屬性的可能值。例如，

1
GET /items?sort=[asc|desc]

中的 sort 參數可以描述為

1
paths:
2
  /items:
3
    get:
4
      parameters:
5
        - in: query
6
          name: sort
7
          description: Sort order
8
          type: string
9
          enum: [asc, desc]

在 YAML 中，您也可以每一行指定一個列舉值

1
enum:
2
  - asc
3
  - desc

列舉中的所有值都必須符合指定的類型。如果您需要為列舉項目指定描述，可以在參數或屬性的 description 中執行此操作

1
type: string
2
enum:
3
  - asc
4
  - desc
5
description: >
6
  Sort order:
7
   * asc - Ascending, from A to Z.
8
   * desc - Descending, from Z to A.

可重複使用的列舉

OpenAPI 3.0 支援可重複使用的列舉定義。

雖然 Swagger 2.0 沒有內建支援可重複使用的列舉，但可以使用 YAML 錨點在 YAML 中定義它們，前提是您的工具支援它們。錨點是 YAML 的一個便利功能，您可以使用 &anchor-name 標記一個鍵，然後在下方使用 *anchor-name 來參照該鍵的值。這讓您可以輕鬆地在 YAML 檔案中複製內容。

注意： 錨點 (&) 必須在使用前定義。

1
definitions:
2
  Colors:
3
    type: string
4
    enum: &COLORS
5
      - black
6
      - white
7
      - red
8
      - green
9
      - blue
10
    # OR:
11
    # enum: &COLORS [black, white, red, green, blue]
12

13
paths:
14
  /products:
15
    get:
16
      parameters:
17
        - in: query
18
          name: color
19
          required: true
20
          type: string
21
          enum: *COLORS
22
      responses:
23
        200:
24
          description: OK

如果您的工具的 YAML 剖析器支援 YAML 合併鍵 (<<)，您可以使用此技巧來參照類型和列舉值。

1
definitions:
2
  Colors: &COLORS
3
    type: string
4
    enum: [black, white, red, green, blue]
5
paths:
6
  /products:
7
    get:
8
      parameters:
9
        - in: query
10
          name: color
11
          required: true
12
          <<: *COLORS
13
      responses:
14
        200:
15
          description: OK

找不到您要尋找的內容嗎？詢問社群
發現錯誤了嗎？讓我們知道