SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场design-api

design-api

编程与开发

查看项目

更新于 10-21 16:24

技能介绍

用途

Design API 用于端到端设计一个 API：从需求出发，生成用户故事（stories），再产出 OpenAPI 规范，经过 lint 校验后迭代完善。这是 Emmanuel Paraskakis 提出的用 LLM 设计 API 的方法。

主要能力

  • 完整的需求到已 lint 规范的流水线。
  • 若用户提供 stories，则跳过故事生成，直接进入规范生成；若未提供，则先生成 stories 并暂停等待评审。
  • 生成符合 OpenAPI 3.1.0（默认）的 JSON 规范，遵循 DRY 原则、组件化结构、SDK 兼容性等最佳实践。
  • 可选通过 RateMyOpenAPI 进行自动 lint 与评分，覆盖 Docs、Completeness、SDK Generation、Security 四个维度。
  • 可选通过 Node.js 与 npx http-server 在本地预览 Swagger UI。

使用方式

用户需提供（或指向）以下文件，文件名不限，按 # Title 标题或内容识别：

始终必需：

  1. Requirements — ICP、需求、痛点、用例、收益。
  2. Domain — 数据对象、属性、枚举、对象关系。
  3. API Standards — 风格指南、命名、路径、安全、错误处理。
  4. OpenAPI Best Practices — 格式规则、DRY 原则、SDK 兼容性、组件结构。

可选（决定入口点）： 5. Stories — 含方法、资源、参数的 API 用户故事。若提供则跳到 Phase 2（规范生成）；若未提供则 Phase 1 生成故事供评审。

若缺少必需文件，需请用户提供后再继续。若用户没有自己的文件，可使用 references/examples/ 中内置的会议示例（conference-research.md、conference-domain.md、API-standards.md、OpenAPI-best-practices.md），不要自行编造新领域。

执行流程：

  • Phase 1（Stories，若已提供 stories 则跳过）：读取输入、识别主题、生成故事（默认简单格式，仅含方法、资源、参数；用户要求详细格式时增加成功响应、错误响应、头部、分页说明）、评审检查点。评审通过后先将最终 stories 保存到文件，再进入 Phase 2。
  • Phase 2（Spec）：读取全部输入，生成单个有效 JSON 文件，默认 OpenAPI 3.1.0。文档结构顺序为 openapi、info、servers、security、tags、paths、components。每个领域对象与枚举都成为组件 schema，集合响应有独立 schema，错误响应使用 RFC 9457（Problem Details），禁止内联 schema，可复用参数、响应、头部放入 components。每个操作、参数、schema、属性、响应、头部都必须有非空描述与示例值，每个操作必须有 summary 和 operationId。命名规则：operationIds 用 camelCase 动词，tags 匹配故事主题名，schemas 用 PascalCase，parameters 用 camelCase。不添加 stories 中不存在的端点、domain 中不存在的属性、standards 中不存在的安全方案。
  • 校验 JSON：确保有效 JSON、每个 $ref 指向存在的组件、无孤立组件、不使用 nullable 关键字（改用 "type": ["string", "null"]）。
  • 保存规范到用户指定位置。
  • 可选 lint：需 RateMyOpenAPI API key，设置环境变量 RMOA_API_KEY。若未设置，尝试 source 用户 shell 配置；仍未设置则跳过自动 lint。设置后通过 curl 上传规范获取评分与问题列表，用 python3 解析（先写入文件再解析，使用 strict=False）。根据问题列表修复：格式或完整性问题自动修复，涉及设计决策的问题询问用户。迭代直到 100/100 或剩余问题为用户批准忽略的有意设计选择。
  • 报告：展示文件路径、总分与四个分项得分、报告 URL、有意忽略的问题列表。
  • 可选 Swagger UI 预览：需 Node.js 与互联网访问。创建 swagger-preview.html，用 npx http-server 在 8090 端口（被占用则试 8091、8092 等）本地服务并打开浏览器。预览结束后清理服务器进程与预览文件。

适用场景

  • 需要从需求出发系统化设计 API 的团队或个人。
  • 希望借助 LLM 生成符合 OpenAPI 最佳实践、可 lint、可评分的 API 规范。
  • 需要先生成用户故事供人工评审、再生成规范的工作流。

限制

  • 核心技能（故事 + 规范生成）无需额外工具，但完整体验需要 RateMyOpenAPI API key（自动 lint 与评分）和 Node.js（本地 Swagger UI 预览）。
  • 无 API key 时仍可生成完整 OpenAPI 规范，只是跳过 lint 与本地预览。
  • 无认证的 API 在 Security 项约得 65 分，RMOA 会标记 8 个以上关于缺少 401/403 的警告；若 API 有意无认证，这些属预期情况。
  • 若用户没有自己的文件，应使用内置会议示例，不要自行编造领域；仅当用户指定领域时才编造。
  • 具体收费、价格、平台等信息暂未提供。