[ADP-763] OpenAPI: 隱式資源指示

指導原則

• 必須(MUST)在 API 描述中記錄隱式資源指示
• 應該(SHOULD)使用清晰簡潔的語言來解釋資源範圍界定
• 當與資源範圍界定相關時，必須(MUST)包含身份驗證和授權要求
• 應該(SHOULD)提供隱式資源指示如何影響 API 回應的示例

概述

在 API 設計中，隱式資源指示是指基於已驗證用戶的上下文或其他非顯式參數返回或操作資源子集的端點。

示例

以下是如何記錄具有隱式資源指示的端點的改進示例:

openapi: 3.1.0
info:
  title: 員工 API
  version: 1.0.0
paths:
  /employees:
    get:
      summary: 獲取已驗證用戶公司的員工
      description: >
        檢索屬於與已驗證用戶關聯的公司的員工列表。
        此端點隱式地將結果範圍限定到用戶的公司，不返回其他公司的員工。
        用戶必須具有 'read:employees' 權限才能訪問此端點。
      tags:
        - 員工
      security:
        - bearerAuth: []
      parameters:
        - name: department
          in: query
          description: 按用戶公司內的部門過濾員工
          schema:
            type: string
      responses:
        '200':
          description: 用戶公司的員工列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
              example:
                - id: "12345"
                  name: "張三"
                  department: "工程"
                  companyId: "67890"
                - id: "67890"
                  name: "李四"
                  department: "市場營銷"
                  companyId: "67890"
        '401':
          description: 未授權 - 用戶未經身份驗證
        '403':
          description: 禁止 - 用戶沒有所需的權限
        '404':
          description: 未找到 - 未找到員工或用戶的公司不存在
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Employee:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        department:
          type: string
        companyId:
          type: string

設計思路

如果 API 的返回結果受到當前使用者認證或權限的影響，但在文件中未明確指出，這可能會導致使用者誤以為自己擁有超出自身權限的能力。

參考資料

• Zalando API Design Guidance

Changelog

• 2025.03.07: Add link to zalando API design guidance.