無程式碼也能輕鬆打造專業LINE官方帳號！一鍵導入模板，讓AI助你行銷加分！
Spec Kit 将自动化规格验证的规范引入 API 开发。
graph LR
A[OpenAPI 规格\nYAML / JSON] --> B[结构验证\nOpenAPI 模式合规性]
B --> C[引用解析\n$ref 验证]
C --> D[一致性检查\n参数匹配]
D --> E[自定义规则\n约定执行]
E --> F[验证报告\n错误 + 警告 + 建议]
F --> G[CI 集成\nGitHub Checks API]
| 验证类别 | 示例检查 | 严重性 |
|---|---|---|
| 结构 | 有效的 OpenAPI 版本、正确的路径结构 | 错误 |
| 模式 | 有效的 JSON Schema、正确的数据类型 | 错误 |
| 引用 | 可解析的 $ref 指针、无循环依赖 | 错误 |
| 一致性 | 匹配的路径参数、唯一的 operationId | 警告 |
| 约定 | 命名模式、说明要求、响应标准 | 警告 |
| 阶段 | 工具 | 目的 |
|---|---|---|
| 设计 | 本地 CLI | 在规格编写期间进行验证 |
| 审查 | PR 检查 | 拉取请求上的自动化审查 |
| 文档 | 文档生成器 | 生成 API 参考文档 |
| 测试 | 模拟服务器 | 根据合约进行验证 |
常见问题
什么是 Spec Kit？ GitHub 的开源工具包，用于验证、linting OpenAPI 规格并从中生成文档。
执行哪些验证检查？ 结构验证、模式验证、引用解析、一致性检查和自定义规则。
如何与 CI/CD 集成？ 可作为 CLI 工具在 GitHub Actions 中运行，支持 GitHub Checks API。
可以生成文档吗？ 是的，从 OpenAPI 规格生成人类可读的 API 文档。
是 GitHub 专用的吗？ 核心工具与任何 OpenAPI 3.x 规格兼容，自定义规则可配置。
延伸阅读
- Spec Kit GitHub 仓库 – 源代码、文档和示例
- OpenAPI 规格 – 官方 OpenAPI 3.x 规格
- GitHub REST API 文档 – 使用 Spec Kit 构建的 GitHub API 文档
- API 设计指南 – REST API 规格设计的最佳实践
