用例
技术文档
API 文档、架构记录、用户指南和运行手册,并配有结构化评审。
概述
API 文档、架构决策记录、用户指南和运行手册都能从结构化的创建与评审流程中受益。Datarim 确保文档准确、完整,并针对真实系统进行测试。该流水线可避免文档写一次就再也不验证的常见失败模式——每个端点都会被检查,每个示例都会被测试,每个链接都会被校验。
示例:支付服务的 API 文档
团队需要为一个包含 12 个端点的支付处理服务编写完整的 API 文档。文档必须面向第三方集成方,并包含三种编程语言的可运行代码示例。
流水线走查
| 阶段 | 发生什么 |
|---|---|
| /dr-init | 范围:12 个端点、请求/响应模式、错误码、认证流程(L2) |
| /dr-prd | 受众:第三方集成方。要求:OpenAPI 3.1、3 种语言的代码示例、沙箱 URL |
| /dr-plan | 优先级:先认证流程,再支付生命周期(创建 → 捕获 → 退款),最后 Webhook |
| /dr-do | 编写文档。与实际 API 代码交叉引用以确保准确性 |
| /dr-qa | 验证:每个端点都有文档、示例已测试、错误码完整、链接有效 |
| /dr-archive(步骤 0.5) | 备注:从实际 API 响应生成示例比手动编写更快 |
主要收益
- 通过交叉引用保证准确性——文档会对照实际 API 代码进行验证,而非基于对行为的假设
- 受众优先的设计——PRD 阶段明确文档的读者及其需求,避免以开发者为中心的盲区
- 经过测试的示例——QA 确保每个代码示例在每种列出的语言中都确实可用
- 活文档——API 变更时可重新运行流水线,由 QA 发现过时的章节
相关智能体
此用例中最活跃的智能体:
复杂度路由
复杂度级别如何应用于技术文档:
- L1——更新单个端点的描述或修复损坏的代码示例
- L2——为包含 10-15 个端点的新 API 编写文档,包括模式和示例
- L3——创建完整的开发者门户,包含指南、教程和参考文档
- L4——多产品文档套件,包含版本管理、迁移指南和 SDK 参考