[ADP-769] OpenAPI 操作

指導方針

回應代碼

• 每個操作必須(MUST)指定至少一個 2xx 成功回應。
• 操作應(SHOULD)包括適當的錯誤回應（4xx 和 5xx）。
• 使用標準 HTTP 狀態碼，如 ADP-200: HTTP 狀態碼 所定義。

操作 ID

• 每個操作必須(MUST)有一個唯一的 operationId。
  • 遵循 ADP-755: OpenAPI operationId 中的命名規範。

API 受眾

• 每個操作必須(MUST)在 x-audience 中指定其 API 受眾。
  • 有關更多資訊，請參見 ADP-752: OpenAPI 受眾。

參數

• 使用操作級別的 parameters 陣列定義所有參數。
• 使用 $ref 來引用在 components 部分定義的通用參數。
  • 遵循 ADP-758: OpenAPI $ref 中有關使用引用的最佳實踐。

請求主體

• 對於接受請求主體的操作（例如，POST、PUT、PATCH），定義 requestBody 對象。
• 指定支持的內容類型（例如，application/json）。
• 使用 $ref 來引用在 components 部分定義的請求架構。

回應

• 定義操作可能返回的所有可能狀態碼的回應。
• 使用 $ref 來引用在 components 部分定義的回應架構。
• 在適當的情況下包含示例，遵循 ADP-756: OpenAPI 提供示例。

安全性

• 如果操作級別的安全要求與全局安全方案不同，則應在操作級別應用安全要求。
• 參考在 components/securitySchemes 部分定義的安全方案。

描述

• 應提供每個操作的清晰簡潔描述。
• 包括有關操作行為的任何重要說明或警告。

廢棄/日落

• 使用 deprecated: true 標記已廢棄的操作。
• 在操作的描述中包含有關廢棄的資訊，例如廢棄原因和建議的替代方案。
• 應參考預定義的共享標頭（參見 ADP-767: 共享公共標頭）以避免冗餘定義。
• 應添加與日落相關的描述，因為僅添加日落標頭並不夠清晰。

速率限制

• 應使用 x-rate-limit 擴展包含速率限制資訊。
• 遵循 ADP-753: OpenAPI x-rate-limit 中的實施細節。
• 應參考預定義的共享標頭（參見 ADP-767: 共享公共標頭）以避免冗餘定義。

可擴展的枚舉

• 對於開放式枚舉，應使用 x-extensible-enum 而不是 enum。
• 遵循 ADP-768: 可擴展的枚舉 中的實施指導。

示例

以下是 OpenAPI 3.1.0 中定義良好的操作示例：

components:
  headers:
    ETag:
      $ref: 'https://vivotek-it.github.io/api-design-principle-beta/models/headers-1.0.0.yaml#/ETag'
  parameters:
    CommonHeader:
      name: Common-Header
      in: header
      required: true
      schema:
        type: string
      description: This is an example header parameter
paths:
  /example:
    get:
      summary: Example endpoint
      parameters:
        - name: Example-Header
          in: header
          required: true
          schema:
            type: string
          description: This is an example header parameter
        - $ref: '#/components/parameters/CommonHeader'
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      description: Creates a new user account with the provided information.
      tags:
        - users
      x-audience: public
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Successful response
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
      x-rate-limit:
        rate: 100
        burst: 200
        unit: minute

相關 ADP

• ADP-200: HTTP 狀態碼
• ADP-752: OpenAPI 受眾
• ADP-753: OpenAPI x-rate-limit
• ADP-755: OpenAPI operationId
• ADP-756: OpenAPI 提供示例
• ADP-758: OpenAPI $ref
• ADP-768: 可擴展的枚舉

參考

• OpenAPI 規範