SuperAPI AI 工具集

api-designer

编程与开发

查看项目

更新于 10-16 23:59

技能介绍

用途

API Designer 是一个面向 REST 与 GraphQL API 设计的技能,定位为资深 API 架构师,专注于生成完整的 OpenAPI 3.1 规范。它用于在编写代码之前,系统性地把业务需求转化为可验证的接口契约:理解领域、建模资源、设计端点、编写规范、模拟验证,并规划长期演进。

主要能力

  • 资源建模:识别资源、关系与操作,在写任何规范前先绘制实体图。
  • 端点设计:定义 URI 模式、HTTP 方法、请求与响应模式。
  • 契约规范:生成 OpenAPI 3.1 规范,并提供校验命令 npx @redocly/cli lint openapi.yaml。
  • 模拟与验证:通过 npx @stoplight/prism-cli mock openapi.yaml 启动模拟服务器来测试契约。
  • 演进规划:设计版本化、弃用与向后兼容策略。
  • 错误处理:采用 RFC 7807 Problem Details,要求 Content-Type: application/problem+json,type 为稳定可文档化的 URI,detail 人类可读且可操作,并可用 errors[] 扩展字段级校验失败。
  • 分页:为所有集合端点实现分页,模板中采用游标分页(cursor、limit)。
  • 认证与授权:文档化认证与授权,模板中提供 BearerAuth(http bearer、JWT)。

使用方式

该技能提供可复制粘贴的模板与工作流。核心工作流为:

  1. 分析领域——理解业务需求、数据模型和客户端需求。
  2. 建模资源——识别资源、关系和操作;写规范前先画实体图。
  3. 设计端点——定义 URI 模式、HTTP 方法、请求/响应模式。
  4. 指定契约——创建 OpenAPI 3.1 规范;继续前先校验。
  5. 模拟并验证——启动模拟服务器测试契约。
  6. 规划演进——设计版本化、弃用和向后兼容策略。

随附的模板包括一个 OpenAPI 3.1 资源端点起步模板(含 /users 与 /users/{id}、游标分页 CursorPage、RFC 7807 Problem、通用错误响应 BadRequest/Unauthorized/NotFound/TooManyRequests 及 BearerAuth 安全方案),以及一个 RFC 7807 错误响应的 JSON 示例。

约束方面,必须遵循 REST 原则(面向资源、正确 HTTP 方法)、使用一致命名约定(snake_case 或 camelCase 二选一并全局应用)、包含完整 OpenAPI 3.1 规范、采用 RFC 7807 错误响应与可操作消息、为所有集合端点实现分页、带清晰弃用策略的 API 版本化、文档化认证授权、提供请求/响应示例。禁止在资源 URI 中使用动词(用 /users/{id} 而非 /getUser/{id})、返回不一致的响应结构、跳过错误码文档、忽略 HTTP 状态码语义、在没有版本化策略的情况下设计 API、在 API 表面暴露实现细节、在没有迁移路径的情况下制造破坏性变更、忽略速率限制考虑。

交付时需提供:资源模型与关系(图或表)、端点规范(URI 与 HTTP 方法)、OpenAPI 3.1 规范(YAML)、认证与授权流程、错误响应目录(所有 4xx/5xx 及 type URI)、分页与过滤模式、版本化与弃用策略,以及校验结果:npx @redocly/cli lint openapi.yaml 无错误通过。

适用场景

适用于需要设计 REST 或 GraphQL API、制定接口契约、统一错误标准、分页与版本策略的开发与架构工作。

限制

该技能是 API 设计辅助,不提供实际运行服务;具体实现语言、框架与部署方式暂未提供;收费与价格暂未提供。

引用文档

以下为作者声明的引用来源,保留指定版本、署名和许可。

作者的来源声明