使用 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
结论
有效地利用componentsOAS 中的对象可以大大增强 API 规范的一致性和可维护性。通过遵循最佳实践并利用 APIGIT 直观的 API 编辑器，开发人员可以制定高效、可重复使用且组织良好的 API 定义。
