SuperAPI AI 工具集

api-design-expert

编程与开发

查看项目

更新于 10-16 09:28

技能介绍

该技能用于指导 API 设计工作,适用场景包括:设计新 API 端点、构建 RESTful API、编写 OpenAPI/Swagger 文档、实现 API 版本控制、设计错误响应、创建 DTO 与校验,以及实现分页、过滤、排序。

使用前会先做项目上下文探查:检查 .agents/memory/ 中的 API 模式与架构说明,审阅现有控制器和 DTO,确认是否已有 OpenAPI/Swagger 配置,并查看版本控制策略。

核心原则包括:RESTful 设计使用名词、复数与层级路径(如 GET /api/users、GET /api/users/:id/posts);使用标准 HTTP 状态码(200、201、204、400、401、403、404、409、500);统一响应格式,单资源为 { "data": {...}, "meta": {...} },列表带 pagination(page、limit、total);统一错误格式,包含 code、message、details、timestamp、path。

最佳实践:命名一致;用 DTO 校验所有输入;提供 OpenAPI/Swagger 文档;所有端点启用认证;列表分页;从项目一开始就做版本控制。

更完整的 DTO 示例、分页/过滤/排序模式、版本控制策略、OpenAPI 配置、CRUD 控制器模式、嵌套资源、批量操作与反模式,见 references/full-guide.md。

限制:资料未提供具体安装命令、收费方式、支持平台及效果数据。