用途:该技能定位为 API 参考文档专家,用于编写开发者易用的 API 手册,包括端点说明、请求示例与错误处理等。
主要能力:按“开发者优先”原则组织文档,强调清晰、一致、完整与可测试。文档结构包含:概览(用途、基础 URL、版本策略)、认证(方式、令牌、请求头与示例)、按资源分组的端点、错误处理(标准错误码与响应)、限流(限额与响应头)、SDK 与客户端库、变更日志。
端点文档格式:说明方法与路径、参数表(参数名、类型、位置、是否必填、描述)、请求示例与响应示例。示例覆盖 curl、JavaScript SDK、Python、Node.js、Go 等语言。
高级能力:过滤、分页(含 X-Total-Count、X-Page、X-Per-Page、Link 响应头)、排序(负号表示降序)、字段选择、幂等性(Idempotency-Key)、限流响应头(X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset)。
数据类型与模式:以 User 对象为例,说明 id、email、created_at、status 等字段类型、格式、示例与枚举值。
最佳实践:统一命名风格(snake_case 或 camelCase)、使用真实示例数据、同时展示成功与错误响应、标注可选与必填参数、说明限流、使用 OpenAPI/Swagger 规范、添加弃用通知、发布前测试所有代码示例。
限制:资料未提供该技能的安装方式、运行环境、收费模式与具体平台支持信息,暂未提供。