用途:定义系统间的集成需求并编写 API 规范,保证前端与后端、服务与服务之间的沟通顺畅。适用场景包括设计新 API 端点(如后端 FRS)、集成第三方服务(如 Stripe、SendGrid)、为合作伙伴编写公开 API 文档、为开发者定义载荷结构。
主要能力:梳理协议(REST、SOAP、GraphQL)、HTTP 方法(GET/POST/PUT/PATCH/DELETE)、状态码(200、201、400、401、403、404、500)。按 Swagger/OpenAPI 风格组织文档,每个端点包含标题与方法、摘要、参数(路径参数、查询参数、请求体、请求头)、成功与错误响应示例、业务规则。还提供集成数据映射表,记录源字段、类型、转换规则、目标字段与备注。
使用方式:按模板编写端点说明,例如 POST /api/v1/orders,请求头含 Authorization: Bearer <token> 与 Content-Type: application/json,请求体为 JSON,并列出约束与成功/错误响应示例。常用工具包括 Swagger / OpenAPI、Postman、Stoplight、Lark Docs / Markdown。
最佳实践:日期统一用 ISO 8601(YYYY-MM-DDThh:mm:ssZ);明确认证方式(API Key 或 OAuth);规定分页默认限制(如 limit=20);定义清晰可读的错误信息。
限制:资料未提供该技能的具体安装命令、运行平台、收费方式或实际效果说明。