API Interface Design

从需求和数据库设计生成或检查系统集成报文、RESTful 接口及可选 OpenAPI 3.1,覆盖触发条件、请求响应、错误、安全、幂等和跨文档追溯。用于接口设计、API 设计、接口文档、报文、OpenAPI 或 Swagger;不要用于排查 API 调用错误、网络问题或 SDK bug。

chenychenyu f041761 12 files · 15.3 KB Updated

File contents

接口设计

模式与契约

  • create:生成接口设计并验证本轮产物。
  • validate:只读执行 38 项检查。
  • review:与 validate 相同,只读给出评审结论,不默认保存报告。
  • repair:用户明确授权后修改既有设计。

至少确认接口目标或调用场景。生成前确认协议、认证、响应包装、分页、幂等和版本策略;这些策略不得被描述成所有项目通用的固定值。

执行流程

  1. 读取唯一规则源:接口标准
  2. 接口分册骨架 开始,按需读取:
  3. 用户要求 OpenAPI/Swagger 时,以 OpenAPI 3.1 模板 生成机器可读契约,并与 Markdown 字段一致。
  4. 建立 spec 功能 → 接口 → DB/词典字段 追溯,执行 IF-A/B/C/D/X 共 38 项检查:先运行 wl-skills-design verify api 获取 [M] 项机械结论(CLI 不可用时由 Agent 代执行),再判 [J] 项,合并为同一编号的报告。

交付约束

  • 响应包装、错误模型和分页格式必须来自项目 profile;未提供时给出推荐值并标注假设。
  • OpenAPI 文件必须可解析,operationId 唯一,schema 引用有效。
  • 验证模式只读;创建模式仅自动修复本轮新产物。
  • 最终说明接口清单、契约、38 项结果和保存状态;只有实际生成或保存的文件才给出路径。

chenychenyu/wl-skills-design/tree/main/files/.github/skills/api-interface-design commit f0417612da

Frequently asked questions

npx skillmds@latest add chenychenyu/api-interface-design