[ADP-702] 可枚舉值約定

指導原則

必須(MUST)使用大寫蛇形命名法(UPPER_SNAKE_CASE)來表示可枚舉值，除非在特定情況下，該可枚舉值在業界普遍使用小寫，則可以例外。
應該(SHOULD)使用基於字串的枚舉而非數值。
- 例外：該可枚舉值為類似 1.0 的版本號碼時。
應該(SHOULD)為每個可枚舉值提供清晰、自我解釋、一致且具描述性的名稱。
- 不應(SHOULD NOT)使用非廣泛認知的縮寫。
- 理想情況下，每個列舉值的含義應該是顯而易見的，使得 API 使用者無需查閱文件即可理解。
可以(MAY)在API文件中為每個可枚舉值提供描述。
在可能的情況下應(SHOULD)使用可擴充式枚舉。。
要棄用某個可枚舉值時，應該(SHOULD)在文件中標記為 deprecated。
整份文件應該(SHOULD)使用同一個枚舉值設計來描述特定資料。

設計思路

雖然"type"欄位的命名通常看起來是可枚舉的，但對於problem+json來說，它必須是一個uri-reference。有關兼容性要求，請參見[ADP-401] HTTP問題基礎。

可枚舉值應在整個API中保持一致，以提高可讀性和可維護性。使用大寫蛇形命名法為可枚舉值提供了明確的視覺區分，並與常見的編程慣例保持一致。

相比於數值，更傾向於使用基於字串的枚舉，因為它們是自文件化的，且不易出錯。它們還能在API回應和文件中提供更好的可讀性。

示例

正確做法:

http

{
  "role": "GROUP_ADMINISTRATOR",
  "status": "ACTIVE",
  "permission": "READ_WRITE"
}

錯誤做法:

http

{
  "role": "groupAdministrator",
  "status": "active",
  "permission": "rw"
}

不建議做法:

http

{
   "role": 1,
   "status": 2,
   "permission": 3
}

如果該值後續不用於計算，則始終返回基於字串的枚舉。

OpenAPI示例

yaml

openapi: 3.0.0
info:
  title: 角色API
  version: 1.0.0
paths:
  /roles:
    get:
      summary: 獲取角色
      responses:
        '200':
          description: 角色列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    role:
                      type: string
                      enum:
                        - GROUP_ADMINISTRATOR
                        - USER
                        - MODERATOR
                      example: GROUP_ADMINISTRATOR
                    status:
                      type: string
                      enum:
                        - ACTIVE
                        - INACTIVE
                        - SUSPENDED
                      example: ACTIVE
    post:
      summary: 創建角色
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                    - GROUP_ADMINISTRATOR
                    - USER
                    - MODERATOR
                  example: GROUP_ADMINISTRATOR
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                  example: ACTIVE
      responses:
        '201':
          description: 角色已創建

參考資料

Changelog

2024.11.11: Add self-explanatory to enum value.

[ADP-702] 可枚舉值約定 ​

指導原則 ​

設計思路 ​

示例 ​

OpenAPI示例 ​

相關ADPs ​

參考資料 ​

Changelog ​

[ADP-702] 可枚舉值約定

指導原則

設計思路

示例

OpenAPI示例

相關ADPs

參考資料

Changelog