接口文档的两种类型

在 AI 开发中，接口文档可以分为两大类：

1. 业务文档

• 定义：描述系统业务逻辑、流程和规则的文档
• 特点：
  • 使用自然语言描述
  • 包含业务场景、用例和流程图
  • 定义业务实体和关系
• AI 开发价值：
  • 帮助 AI 理解业务上下文
  • 提供领域知识背景
  • 辅助生成符合业务逻辑的代码

2. API 文档

• 定义：详细描述接口技术规范的文档
• 特点：
  • 使用结构化格式（如 OpenAPI/Swagger）
  • 包含端点、参数、返回值等
  • 有明确的请求/响应示例
• AI 开发价值：
  • 提供精确的接口调用规范
  • 减少 AI 猜测和错误
  • 支持自动生成客户端代码

两种文档的配合使用

通过业务文档和 API 文档的配合，可以显著提高 AI 开发效果：

1. 上下文理解：业务文档提供"为什么"，API 文档提供"怎么做"
2. 代码生成：AI 可以结合业务逻辑生成符合技术规范的代码
3. 错误减少：双重验证机制降低 AI 误解的可能性
4. 效率提升：减少人工解释和修正的时间

最佳实践

1. 保持两种文档的同步更新
2. 在业务文档中引用相关 API 文档
3. 在 API 文档中添加业务场景说明
4. 使用工具自动生成 API 文档（如 Swagger）
5. 为 AI 提供两种文档的完整访问权限

插件推荐

Vs code 有一个插件，叫 REST Client 这个可以直接生成文档进行调试。 也是用 MarkDown 格式的，这里做一个推荐。