api-design-reviewer

用途：面向工程团队的 REST API 设计审查工具，帮助构建一致、可维护、符合规范的接口。主要能力包括三类：一是 API lint，检查资源命名（kebab-case URL、camelCase 字段）、HTTP 方法使用、URL 结构、状态码合规、错误格式一致性与文档覆盖率；二是破坏性变更检测，识别端点删除、响应结构变化、字段删除或重命名、类型变化、新增必填字段和状态码变化，并给出迁移指南；三是设计评分卡，按一致性 30%、文档 20%、安全 20%、可用性 15%、性能 15% 加权计分并给出 A–F 等级与建议。使用方式为三个命令行工具，命令保持原样：python scripts/api_linter.py openapi.json --format json；python scripts/breaking_change_detector.py v1.json v2.json --exit-on-breaking；python scripts/api_scorecard.py openapi.json --min-grade B。按任务选择输出类型，并确认待审规范文件、质量门槛或 CI 门禁要求。适用场景包括新 API 设计评审、OpenAPI/Swagger 规范校验、版本管理与变更检测、CI 中以设计质量为上线门禁。限制：仅覆盖 OpenAPI 3.x 与 Swagger 2.0 的 JSON 规范；不涉及运行时测试、负载测试或契约测试，不支持 GraphQL、gRPC、WebSocket，也不自动从代码生成规范或实现认证流程。使用细节可查阅 rest-design-patterns、tooling-ci-and-troubleshooting、rest_design_rules、api_antipatterns 等参考文档。