安装命令
npx skills add https://github.com/danhvb/my-ba-skills --skill 'API Documentation'🇨🇳中文介绍
API 文档技能
目的
定义集成需求并记录 API 规范，以确保系统间（例如前端与后端，或服务与服务之间）的顺畅通信。
使用时机
- 设计新的 API 端点（例如，为后端编写功能需求规格说明书）。
- 与第三方服务集成（例如 Stripe、SendGrid）。
- 为合作伙伴记录公共 API。
- 为开发人员定义负载结构。
业务分析师需掌握的关键 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 风格）
每个端点必需的章节
- 标题与方法：
GET /api/v1/users/{userId} - 摘要 ：一行描述其功能。
- 参数 ：
- 路径参数 ：URL 中必需的 ID（例如
{userId}）。 - 查询参数 ：过滤/排序限制（例如
?limit=10&role=admin）。 - 请求体 ：JSON 负载（用于 POST/PUT）。
- 请求头 ：身份验证令牌、Content-Type。
- 路径参数 ：URL 中必需的 ID（例如
- 响应示例 ：
- 成功（200）的 JSON 响应体。
- 错误（4xx/5xx）的 JSON 响应体。
- 业务规则 ：约束条件、逻辑、副作用。
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 |
工具
- Swagger / OpenAPI ：开发文档标准。
- Postman ：测试 API 调用。
- Stoplight ：可视化 API 设计。
- Lark Docs / Markdown ：为业务需求文档/功能需求规格说明书编写规范。
最佳实践
- 保持一致性 ：日期使用 ISO 8601 格式（
YYYY-MM-DDThh:mm:ssZ）。 - 身份验证 ：明确说明身份验证如何工作（API 密钥与 OAuth）。
- 分页 ：不要返回一百万条记录。指定默认限制（
limit=20）。 - 错误信息 ：定义清晰、人类可读的错误信息。
参考
- RESTful API 设计指南。
- OpenAPI 规范。
每周安装次数
–
代码仓库
首次出现时间
–
安全审计
🇺🇸English
API Documentation Skill
Purpose
Define integration requirements and document API specifications to ensure smooth communication between systems (e.g., Frontend to Backend, or Service to Service).
When to Use
- Designing new API endpoints (e.g., FRS for Backend).
- Integrating with 3rd party services (e.g., Stripe, SendGrid).
- Documenting public APIs for partners.
- Defining payload structures for developers.
Key API Concepts for BAs
1. Protocols
- REST (Representational State Transfer) : Most common. Resource-based.
- SOAP : Older, XML-based. Heavy enterprise use.
- GraphQL : Flexible, query-based. Client asks for exactly what it needs.
2. HTTP Methods (Verbs)
- GET : Retrieve data (Read).
- POST : Create new data (Create).
- PUT : Update/Replace full data (Update).
- PATCH : Update partial data (Update).
- DELETE : Remove data (Delete).
3. Status Codes
- 200 OK : Success.
- 201 Created : Success (new resource made).
- 400 Bad Request : Client error (invalid input).
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者，精准高效
