[ADP-768] 可擴充列舉

原則

針對開放式列舉，應該(SHOULD)使用 x-extensible-enum 而非 enum。
當使用 x-extensible-enum 時，必須(MUST)在文件中明確說明可能的擴展方式。
應該(SHOULD)為 x-extensible-enum 提供初始值集合，但不應將其視為完整或固定的集合。
客戶端應該(SHOULD)能夠處理未知的枚舉值，而不是在遇到未知值時失敗。

每個可擴充列舉值應該(SHOULD)提供以下內容:

屬性	必需	預設值	描述
value	是	n/a	可擴充列舉值。必須符合指定的類型。
description	是	n/a	描述該值的語義含義。
deprecated	否	false	布林值，指定此列舉值的棄用狀態。

說明

可擴充枚舉允許 API 提供者在不破壞向後兼容性的情況下添加新的枚舉值。這對於需要隨時間演進的 API 特別有用，可以避免因添加新值而導致的版本變更。

示例

以下是使用 x-extensible-enum 的 OpenAPI 3.1 規範示例:

yaml

openapi: 3.1.0
info:
  title: 訂單 API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: 獲取訂單列表
      parameters:
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderStatus'
      responses:
        '200':
          description: 成功獲取訂單列表
          content:
            application/json:    
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  schemas:
    OrderStatus:
      type: string
      x-extensible-enum:
        - value: PENDING
          description: 等待處理的訂單
        - value: PROCESSING
          description: 正在處理的訂單
        - value: COMPLETED
          description: 已完成的訂單
        - value: CANCELLED
          description: 已取消的訂單
        - value: REFUNDED
          description: 已退款的訂單
        - value: ON_HOLD
          description: 暫時擱置的訂單
          deprecated: true
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/OrderStatus'

[ADP-768] 可擴充列舉

原則

說明

示例

相關 ADP

參考資料

[ADP-768] 可擴充列舉 ​

原則 ​

說明 ​

示例 ​

相關 ADP ​

參考資料 ​

[ADP-768] 可擴充列舉

原則

說明

示例

相關 ADP

參考資料