[ADP-751] 新的 OpenAPI 文件

指導

必須(MUST)使用 OpenAPI 3.1.0 或更高版本
yaml
```
openapi: 3.1.0
```
必須(MUST)使用 YAML 格式以提高可讀性和便於拆分
- JSON 格式會導致深層嵌套的對象，難以閱讀和維護
必須(MUST)將所有回應架構移至 components 部分
- 詳見 ADP-758: OpenAPI 中 $ref 的使用

必須(MUST)在 info 部分包含以下元數據:

title: API 名稱
description: API 目的的簡要概述
version: 遵循 ADP-24: 版本控制機制的 API 版本

contact: API 支持資訊 (參見 ADP-759: OpenAPI 聯繫資訊)

示例:

yaml

info:
  title: 用戶管理 API
  description: 用於管理用戶帳戶和個人資料的 API
  version: 1.0.0
  contact:
    name: API 支持團隊
    url: https://example.com/support
    email: api-support@example.com

應該(SHOULD)在 components 部分定義安全方案

必須(MUST)對操作或整個 API 應用適當的安全要求

示例:

yaml

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

應該使用標籤來分組相關操作

必須為所有標籤提供描述

示例:

yaml

tags:
  - name: users
    description: 用戶管理操作
  - name: auth
    description: 認證和授權操作

必須使用 kebab-case 命名路徑段
必須使用 camelCase 命名查詢參數和操作 ID
應該為每個操作提供摘要和描述

必須為操作使用適當的 HTTP 方法 (參見 ADP-110: HTTP 方法)

示例:

yaml

paths:
  /users/{userId}:
    get:
      summary: 獲取用戶詳情
      description: 檢索特定用戶的詳細資訊
      operationId: getUserDetails
      tags:
        - users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功回應
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

應該為請求體和回應提供示例 (參見 ADP-756: OpenAPI 提供示例)
必須在 components 部分定義常見錯誤回應
應該使用標準 HTTP 狀態碼 (參見 ADP-138: HTTP 狀態碼)
必須遵循問題詳情格式進行錯誤回應 (參見 ADP-401: HTTP 問題基礎)
如果 API 支持 webhooks，應該定義它們 (參見 ADP-760: OpenAPI Webhooks)
應該(SHOULD)對您的 OpenAPI 文件進行版本控制。
DRAFT 對 API 定義的更新必須(MUST)需要代碼審查，並且應該取決於服務更新的整體架構審查。

關聯 ADPs

參考

Changelog

2024.10.17 add version control

[ADP-751] 新的 OpenAPI 文件 ​

指導 ​

關聯 ADPs ​

參考 ​

Changelog ​

[ADP-751] 新的 OpenAPI 文件

指導

關聯 ADPs

參考

Changelog