使用 OpenAPI 定義可重複使用元件
APIGit
2023-06-15
OpenAPI 規範 (OAS) 提供了一種強大且標準化的方法來描述 API。該規範最有價值的功能之一是components 對象，它允許跨 API 重複使用各種元素，確保一致性並減少冗餘。
了解 OAS 中的組件
這components 物件可以包含模式、參數、回應、標頭、請求正文、安全方案和範例。這個集中式容器增強了 API 定義的可重複使用性和可維護性。
常用的重複使用元件
模式
模式定義請求和回應主體的結構。它們可以表示使用者物件、錯誤訊息結構或任何其他資料實體。
例子:
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
參數
參數可在多個操作中重複使用，例如路徑中的 id 或分頁的限制和偏移量。
例子:
components:
parameters:
userId:
name: userId
in: path
required: true
schema:
type: integer
limitParam:
name: limit
in: query
schema:
type: integer
default: 10
回應
通用回應結構（尤其是錯誤處理）可以定義一次並重複使用，從而確保一致的 API 行為。 例子:
components:
responses:
NotFound:
description: The specified resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
標頭
可以跨不同端點使用的標準標頭可以定義一次並重複使用。
例子:
components:
headers:
X-Rate-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
安全方案
定義通用安全方案可讓您在 API 中重複使用它們，從而確保一致的安全實務。
例子：
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
可重複使用性的最佳實踐
命名約定
為元件使用清晰、描述性的名稱，使開發人員更容易理解和重複使用它們。例如，User 表示使用者物件架構，NotFound 表示常見的 404 錯誤回應。
組織架構
邏輯地組織您的元件，也許可以按其類型（例如，回應、參數）或按其領域區域（例如，身份驗證、使用者、產品）對它們進行分類。
避免過度模組化
雖然可重用性是關鍵，但過多的粒度可能會使 API 規範的理解和維護變得複雜。平衡至關重要。
範例場景
常見錯誤回應架構
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
重複使用查詢參數進行分頁
paths:
/users:
get:
parameters:
- $ref: '#/components/parameters/limitParam'
- name: offset
in: query
schema:
type: integer
default: 0
共享授權標頭
paths:
/protected/resource:
get:
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
結論
有效地利用components OAS中的物件可以大大增強您的API規範的一致性和可維護性。透過遵循最佳實務並利用 APIGIT 直覺的 API 編輯器，開發人員可以製作高效、可重複使用且組織良好的 API 定義。
