S
SkillsMD 发现、学习和掌握最新的 AI 技术 Skills。基于真实社区数据,为开发者提供最权威的 AI 工具导航。
关于 聚焦 AI 技术 Skills 每周数据更新 中英双语文档 © 2026 SkillsMD. All rights reserved.
API文档编写指南:REST/GraphQL规范、Swagger模板与集成映射 | SkillsMD
首页 / Skills / api-documentation API文档编写指南:REST/GraphQL规范、Swagger模板与集成映射 API Documentation by danhvb/my-ba-skills
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。
响应示例 :
成功(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_nameStr 拼接 FullNameStr A.first + " " + A.last last_nameStr (同上) - - dobDate 格式化为 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 规范。
每周安装次数
–
代码仓库
danhvb/my-ba-skills
首次出现时间
–
安全审计
Gen Agent Trust HubPass SocketPass SnykPass
🇺🇸 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 开发者,精准高效
联系我们 statusEnum 映射 'Active'->1 IsActiveBool 逻辑映射
401 Unauthorized : Authentication missing/failed.
403 Forbidden : Authentication passed, but permission denied.
404 Not Found : Resource doesn't exist.
500 Internal Server Error : Backend crashed.
Documentation Structure (Swagger/OpenAPI Style)
Required Sections per Endpoint
Title & Method : GET /api/v1/users/{userId}
Summary : One-line description of what it does.
Parameters :
Path Params : Required ID in URL (e.g., {userId}).
Query Params : Filter/Sort limits (e.g., ?limit=10&role=admin).
Body : JSON payload (for POST/PUT).
Headers : Auth tokens, Content-Type.
Response Examples :
Success (200) JSON body.
Error (4xx/5xx) JSON body.
Business Rules : Constraints, logic, side effects.
API Specification Template (Simple)
Endpoint: Create New Order Method : POST URL : /api/v1/orders Description : Creates a new customer order and reserves inventory.
Authorization: Bearer <token>
Content-Type: application/json
{
"customerId": "uuid-string",
"items": [
{
"productId": "uuid-string",
"quantity": 2
}
],
"shippingAddress": {
"street": "123 Main St",
"city": "Startown"
}
}
quantity must be > 0.
customerId must be active.
Max 20 items per order.
Success Response (201 Created) :
{
"orderId": "ord-12345",
"status": "PENDING",
"totalAmount": 150.00,
"createdAt": "2026-01-21T10:00:00Z"
}
400 Bad Request : "Invalid Quantity" or "Product Out of Stock".
401 Unauthorized : Token expired.
Mapping Integrations (Data Mapping) When connecting System A to System B, create a Mapping Table:
Source Field (System A) Type Transformation Destination Field (System B) Type Notes first_nameStr Concat FullNameStr A.first + " " + A.last last_nameStr (above) - - dobDate Format YYYY-MM-DD BirthDateStr B requires string format statusEnum Map 'Active'->1 IsActiveBool Logic mapping
Tools
Swagger / OpenAPI : Standard for dev docs.
Postman : Testing API calls.
Stoplight : Visual API design.
Lark Docs / Markdown : Writing specs for BRD/FRS.
Best Practices
Be Consistent : Use ISO 8601 for dates (YYYY-MM-DDThh:mm:ssZ).
Authentication : Explicitly state how auth works (API Key vs OAuth).
Pagination : Don't return 1 million records. Specify default limits (limit=20).
Error Messages : Define clear human-readable error messages.
Reference
RESTful API Design Guide.
OpenAPI Specification (OAS).
Lark CLI IM 即时消息管理工具:机器人/用户身份操作聊天、消息、文件下载
23,600 周安装