API Documentation

API 文档编写技能

用途

定义集成要求并编写 API 规范，确保系统间顺畅通信（例如，前端与后端之间，或服务与服务之间）。

使用场景

• 设计新的 API 端点（例如，后端的 FRS）。
• 与第三方服务集成（例如，Stripe、SendGrid）。
• 为合作伙伴编写公共 API 文档。
• 为开发人员定义载荷结构。

BA 需要了解的 API 概念

1. 协议

• REST（表述性状态转移）：最常见，基于资源。
• SOAP：较早的协议，基于 XML，在大型企业中广泛使用。
• GraphQL：灵活、基于查询；客户端可按需请求数据。

2. HTTP 方法（动词）

• GET：检索数据（读取）。
• POST：创建新数据（创建）。
• PUT：更新／替换完整数据（更新）。
• PATCH：更新部分数据（更新）。
• DELETE：删除数据（删除）。

3. 状态码

• 200 OK：成功。
• 201 Created：成功（已创建新资源）。
• 400 Bad Request：客户端错误（输入无效）。
• 401 Unauthorized：缺少身份验证或身份验证失败。
• 403 Forbidden：身份验证通过，但权限不足。
• 404 Not Found：资源不存在。
• 500 Internal Server Error：后端发生故障。

文档结构（Swagger/OpenAPI 风格）

每个端点的必需部分

1. 标题和方法：GET /api/v1/users/{userId}
2. 摘要：用一行描述端点的功能。
3. 参数：
   • 路径参数：URL 中必需的 ID（例如，{userId}）。
   • 查询参数：筛选／排序限制（例如，?limit=10&role=admin）。
   • 请求体：JSON 载荷（用于 POST/PUT）。
   • 请求头：身份验证令牌、Content-Type。
4. 响应示例：
   • 成功（200）时的 JSON 请求体。
   • 错误（4xx/5xx）时的 JSON 请求体。
5. 业务规则：约束、逻辑、副作用。

API 规范模板（简易版）

端点：创建新订单

方法：POST URL：/api/v1/orders 说明：创建新客户订单并预留库存。

请求头：

• Authorization：Bearer <token>
• Content-Type：application/json

请求体（JSON）：

{
  "customerId": "uuid-string",
  "items": [
    {
      "productId": "uuid-string",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Startown"
  }
}

约束：

• quantity 必须大于 0。
• customerId 必须处于活跃状态。
• 每笔订单最多 20 件商品。

成功响应（201 Created）：

{
  "orderId": "ord-12345",
  "status": "PENDING",
  "totalAmount": 150.00,
  "createdAt": "2026-01-21T10:00:00Z"
}

错误响应：

• 400 Bad Request：「数量无效」或「商品缺货」。
• 401 Unauthorized：令牌已过期。

集成映射（数据映射）

连接系统 A 和系统 B 时，请创建映射表：

来源字段（系统 A）	类型	转换	目标字段（系统 B）	类型	备注
first_name	Str	拼接	FullName	Str	A.first + " " + A.last
last_name	Str	（同上）	-	-
dob	Date	格式 YYYY-MM-DD	BirthDate	Str	B 要求字符串格式
status	Enum	将 'Active' 映射为 1	IsActive	Bool	逻辑映射

工具

• Swagger / OpenAPI：开发文档的标准。
• Postman：测试 API 调用。
• Stoplight：可视化 API 设计。
• Lark Docs / Markdown：编写 BRD/FRS 规范。

最佳实践

• 保持一致：日期使用 ISO 8601 格式（YYYY-MM-DDThh:mm:ssZ）。
• 身份验证：明确说明身份验证方式（API Key 或 OAuth）。
• 分页：不要一次返回 100 万条记录。指定默认限制（limit=20）。
• 错误消息：定义清晰、易于理解的错误消息。

参考资料

• RESTful API 设计指南。
• OpenAPI 规范（OAS）。