[ADP-761] OpenAPI: 公共共享架構

指導原則

• 應該(SHOULD)將穩定的架構發布到公共網站，以便在項目/團隊之間重用。
• 必須(MUST)按照 ADP-24 中概述的語義化版本控制來為已發布的架構進行版本管理。
• 應該(SHOULD)徹底記錄所有已發布的架構，包括每個屬性(property)的描述。
• 更新已發布的架構時必須(MUST)確保向後兼容，或者如果需要進行破壞性更改，則增加主版本號。

什麼值得發布?

• ProblemDetail 架構: 用於表示 HTTP 問題詳情的標準化架構。
• ErrorResponse 架構: API 錯誤回應的通用架構。
• ErrorResponseExample 架構: 不同錯誤回應的示例架構。
• CloudEvent 架構: CNCF 定義的 CloudEvents 架構。
• Pagination 架構: 分頁回應的通用架構。
• SortOrder 架構: 定義請求中排序順序的架構。
• Filter 架構: 過濾請求的通用架構。

不建議發布什麼架構?

• Object 架構:
  • 這些架構變化太頻繁。
  • 如果您想發布，請使用版本控制來管理更新並確保向後兼容性。

共享架構的好處

1. 一致性: 使用共享架構確保常見數據結構在不同 API 之間保持一致。
2. 可維護性: 集中管理架構簡化了更新和更改過程。
3. 效率: 減少定義和記錄常見結構的重複工作。
4. 互操作性: 促進不同服務和系統之間更容易的集成。

實施細節

發布流程

1. 在團隊內審核和批准架構。
2. 根據 ADP-24 對架構進行版本控制。
3. 將架構發布到指定的公共存儲庫或 API 註冊表。
4. 更新文件以反映新的或更新的架構。

引用已發布的架構

引用已發布的架構時，使用特定版本的完整 URL:

components:
  schemas:
    Error:
      $ref: 'https://api.example.com/schemas/v1/Error.yaml'

示例

問題詳情 (HTTP Problem)

ProblemDetails:
  type: object
  properties:
    type:
      type: string
      format: uri
    title:
      type: string
    status:
      type: integer
      format: int32
    detail:
      type: string
    instance:
      type: string
      format: uri
  required:
    - type
    - title
    - status
    - detail

CloudEvents

CloudEvent:
  type: object
  properties:
    specversion:
      type: string
      enum: ["1.0"]
    type:
      type: string
    source:
      type: string
      format: uri
    id:
      type: string
    time:
      type: string
      format: date-time
    datacontenttype:
      type: string
    data:
      type: object
  required:
    - specversion
    - type
    - source
    - id

最佳實踐

1. 保持架構盡可能簡單和通用，以最大化重用性。
2. 為每個架構提供清晰的文件，包括使用示例。
3. 建立架構更新和版本控制的治理流程。
4. 根據反饋和不斷發展的需求定期審查和更新共享架構。
5. 考慮為流行的編程語言創建特定語言的綁定或代碼生成工具。

相關 ADP

• ADP-24: 版本控制機制
• ADP-758: OpenAPI 中使用 $ref
• ADP-401: HTTP Problem 基礎
• ADP-602: CloudEvents

參考資料

• OpenAPI 規範
• JSON Schema
• CloudEvents 規範
• RFC 7807: HTTP API 的問題詳情
• Zalando RESTful API 指南