[ADP-762] OpenAPI: HTTP Profile 基礎

指導原則

• 應該(SHOULD)使用 OpenAPI schema 作為 HTTP Profile 基礎
• 引用組件時必須(MUST)遵循 ADP-758: OpenAPI $ref
• 應該(SHOULD)使用 ADP-756: OpenAPI 提供示例 來說明 profile 的使用
• 更新 schema 時必須(MUST)遵守 ADP-24: 版本控制機制

將 Profiles 與 OpenAPI Schema 結合

Profiles 可以與 OpenAPI Schema 結合，提供豐富的語義和約束。OpenAPI Schema 主要用於描述 API 的結構和驗證規則，而 profiles 可以提供額外的語義和約定。

1. 定義 Profile

   • 定義描述特定資源的額外語義和約束的 profile。
   • 示例:
     • Profile URI: http://example.com/profiles/user-profile
     • 描述: 此 profile 為用戶資源定義了額外的語義，包括驗證規則和業務約束。

2. 在 OpenAPI Schema 中引用 Profile

   • 使用 Link 標頭或 _links 屬性(property)在資源表示中鏈接 profiles。
   • 引用 profile 的 OpenAPI Schema 示例:

openapi: 3.1.0
info:
  title: 用戶 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 獲取用戶列表
      responses:
        '200':
          description: 用戶列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              examples:
                example1:
                  value:
                    - name: 張三
                      email: zhangsan@example.com
                      _links:
                        profile:
                          href: "http://example.com/profiles/user-profile"
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        _links:
          type: object
          properties:
            profile:
              type: object
              properties:
                href:
                  type: string
                  format: uri
                  example: "http://example.com/profiles/user-profile"

相關 ADP

• ADP-24: 版本控制機制
• ADP-756: OpenAPI 提供示例
• ADP-758: OpenAPI $ref
• ADP-701: 屬性設計

參考資料

• OpenAPI 規範
• JSON Hyper-Schema
• RFC 6906: 'profile' 鏈接關係類型