SuperAPI AI 工具集

best-openapi-design

编程与开发

查看项目

更新于 11-06 21:01

技能介绍

该技能名为 Best OpenAPI Design,来自 saltbo/bstack,旨在把 HTTP API 当作长期存在的资源协议来对待。其核心思路是先发现稳定的领域资源,再定义路由,并通过 OpenAPI 契约、实现和验证全程保持 HTTP 语义。

用途方面,它用于设计、评审、实现和强制执行严格资源导向的 RESTful HTTP API 与 OpenAPI 契约,适用于判断某个概念应建模为字段还是资源、决定 API 路径与方法、编写或更新 OpenAPI 描述、以及审查现有 API 是否符合资源导向原则等场景。

主要能力包括:按权威顺序解决设计问题(先遵循 IETF HTTP RFC,再保持 Fielding REST 约束,再保持已发布契约与项目策略,最后应用本技能基线配置);强制“只暴露资源”规则,拒绝动作导向路径,如 POST /orders/{orderId}/cancel,并给出资源化建模方式,如 POST /orders/{orderId}/cancellation-requests;提供资源建模、HTTP 契约定义、OpenAPI 发布与演进、框架集成、验证与报告等分步流程;定义基线契约配置,包括命名规范、版本头、响应结构、分页配置、过滤参数、错误模型、请求 ID、认证与授权分离、条件写入、幂等性、长任务资源化等规则;要求使用脚本检查路径中的显式动词,并以资源证明、路径动词审计、RPC 形状审计等报告结果。

使用方式上,该技能以文档和规则集形式提供,用户需在 API 设计或评审过程中按步骤阅读对应参考文件(如 references/resource-modeling.md、references/http-contract.md 等),执行路径检查脚本,并遵循资源门禁与分页配置等决策点。当无法证明资源模型或分页配置时,应停止并报告缺失决策。

适用场景包括:新 API 设计、现有 API 评审与演进、OpenAPI 契约编写与维护、在项目中统一 API 风格、以及需要强制执行资源导向约束的团队协作。

限制方面,该技能明确禁止动作导向路径,这是一项比 HTTP 或 REST 要求更严格的政策;它不把 Google AIP、GitHub REST 等成熟 API 视为权威,只作为证据;不复制 RPC 转码、protobuf 约定、旧式分页、自定义错误封装等;要求项目在无冲突约定时应用基线配置,并保持已发布公共契约兼容;对于无法通过资源模型表达的能力,要求失败关闭并报告缺失的领域决策。关于收费、价格、平台支持等具体信息,资料未提供。