API 文档

API 文档是开发者产品的 主界面。Reference 要完整准确；Guides 要可跑通——二者通过 OpenAPI 与示例代码衔接。

学习目标

• 理解 OpenAPI 在 Reference 生成中的角色
• 掌握 REST 端点文档的标准字段结构
• 建立 Docs Generation 与手工 Guide 的分工

核心概念

Reference 页结构

区块	内容
概述	资源含义、典型用例
请求	Method、Path、Headers、Body schema
响应	状态码、Body、错误体
示例	curl + 一种 SDK（可选）
变更	自 vX 起、Deprecated 字段

POST /api/tracks 示例应含 必填字段、默认值、409 冲突场景。

OpenAPI 工作流

源码注解 / 手写 openapi.yaml
  → Spectral Lint（规范检查）
  → Redoc / Swagger UI 渲染
  → CI 与实现 diff（drift 告警）

Single source of truth：实现与 spec 不一致时，以可测 spec 或契约为准，尽快对齐。

Guides vs Reference

Quickstart — 最小路径拿到第一个 201 Created
How-to — 分页、过滤、批量导入
Reference — 每个 query param 类型与约束
Concepts — 资源模型、Slug 规则、幂等

Reference 回答 「这个参数是什么」；Guide 回答 「我要完成什么任务」。

Docs Generation 边界

• 可生成：路径列表、Schema 表格、Try-it-out
• 需人工：认证流程、Rate limit 策略、Migration、最佳实践
• 需测试：示例命令在 CI 跑通（contract test）

练习

• 为 GET /api/tracks/{slug} 写 Reference 大纲（含 404）
• 列出 openapi.yaml 中 tracks 资源的 5 个字段说明
• 写 5 行 curl Quickstart：创建 track 并 GET 验证

小结

OpenAPI 保 Reference 同步；Guides 保任务完成；CI 保示例可跑。 下一课把文档放进内容营销漏斗。