DocDriven

DocDriven 是什么

DocDriven 是面向前端、后端、产品和设计团队的可视化 API 设计平台，由丹麦公司 Nordicode ApS 运营。它把接口设计、文档、Mock 服务、评审、变更记录和 AI 代码生成集中在共享工作区。

这里的“设计”指端点、请求、响应和数据 Schema 设计，不是图片、Logo 或界面素材生成。它适合在正式开发前对齐 API 契约，减少前后端等待和破坏性变更。

主要功能概览

可视化 API 设计

团队可在界面中创建端点、方法、参数、请求体、响应和数据模型，减少直接编辑 YAML 时的结构错误。自动补全和基于已有属性的建议有助于保持命名与 Schema 一致。

• 后端开发者可在编码前确定资源、错误模型和版本策略。
• 前端开发者可提前确认页面所需字段和交互流程。
• 产品经理可查看接口进度、责任人和未解决问题。
• UI 设计师可核对界面需要的数据是否已在契约中体现。
• 外部访客可参与特定项目评审，而不必拥有整个工作区权限。

可视化编辑不能替代 API 治理。团队仍需定义认证、授权、幂等、分页、错误码、速率限制和兼容性规则。

OpenAPI 导入与统一文档

新项目既可以从空白开始，也可以导入现有 OpenAPI 规范。这样可把分散的内部与外部接口放到统一工作区，作为前后端和利益相关者共同查看的契约。

1. 创建工作区和项目，或选择导入现有规范。
2. 检查端点、Schema、示例和安全定义是否完整导入。
3. 补充业务说明、错误响应和边界条件。
4. 邀请成员或外部访客评审，并分配待处理问题。
5. 发布确认后的 API 版本，建立变更基线。
6. 让前端连接 Mock Server，后端按契约实现。

导入成功不代表规范语义完全正确。循环引用、自定义扩展、安全方案和复杂多态模型需要单独测试。

Mock Server 如何使用

DocDriven 可根据 API 设计创建即时云端 Mock Server，让调用方在真实后端尚未完成时测试请求和响应。前端、移动端和自动化测试可以围绕同一契约并行工作。

• 为响应定义有代表性的成功、校验失败、未授权和服务器错误示例。
• 不要把生产密钥、真实个人信息或客户数据写入示例。
• 确认 Mock 响应的状态码、头部和延迟是否覆盖客户端逻辑。
• 后端上线后用契约测试比较真实实现与设计。

Mock Server 只是模拟服务，不证明真实后端的性能、安全、事务和数据一致性已经满足要求。

实时协作与责任管理

团队成员可以查看计划变更、评论接口方案、报告问题并指定负责人。项目访客只访问被邀请的项目，不能查看其他项目或管理工作区设置。

评审记录应说明决策原因、兼容影响和迁移计划，而不只是标记完成。涉及公共或合作伙伴 API 时，还应建立正式审批和发布门禁。

Changelog 与 Baseline

Baseline 会捕获某一时间点的 API 状态，并将后续设计与之比较。差异按新增、删除和修改的端点或 Schema 分类，帮助团队尽早发现可能破坏客户端的变化。

• 在稳定发布前建立明确基线。
• 检查字段删除、类型修改、必填状态和请求结构变化。
• 为破坏性变更制定新版本和迁移期限。
• 在 Changelog 中补充业务背景、发布日期和升级动作。
• 将差异评审纳入 Pull Request 或发布流程。

自动差异能发现结构变化，但未必理解业务语义。字段含义、默认值或权限变化即使 Schema 不变，也可能影响调用方。

AI Code Assistant

Code Assistant 会参考 GitHub 仓库中的示例文件和团队配置，为 DocDriven 中的端点或 Schema 生成代码。它的目标是跟随现有约定生成样板实现，而不是自主完成全部业务逻辑。

配置文件要求

仓库根目录需要 docdriven.config.json，每个模板包含名称、示例文件、输出目录和目标类型。目标可以是 Endpoints 或 Schemas，示例文件用于提示生成代码的结构与风格。

输出方式

• 创建 Pull Request，供开发者评审后合并。
• 提交到当前选择的分支。
• 提交到其他分支或其他已授权仓库。
• 在日志页查看生成过程、失败和完成状态。

优先选择 Pull Request，并让测试、静态分析和人工审查共同把关。生成代码可能包含错误、过度权限、不安全输入处理或与业务规则不符的实现。

GitHub 连接与安全

使用 Code Assistant 需要通过 GitHub 授权，使 DocDriven 可以访问仓库、读取代码示例并提交生成内容。授权范围对私有代码和供应链安全有直接影响。

• 只授权确实需要的组织和仓库。
• 使用专用分支、受保护主分支和强制 Pull Request 审查。
• 不要在示例文件、配置或日志中放置密钥。
• 定期检查 GitHub 应用权限并撤销不再使用的连接。
• 对生成依赖运行漏洞、许可证和恶意包检查。
• 离职、项目结束或试用停止时立即回收访问权。

价格与套餐

试用无需信用卡，结束后必须选择付费计划，否则账户会被暂停，直到订阅或关闭账户。Team 显示价格可能受月付、年付、税费和地区影响，至少三席意味着最低团队成本高于单席价格。

升级会按当前周期进行比例计费，降级从下一计费周期生效。公开页面未提供清晰退款规则，付款前应确认续费、取消、未使用周期和税费处理。

隐私与数据处理

隐私政策所列运营主体为 Nordicode ApS，更新时间为 2023 年 12 月。平台会处理姓名、邮箱、账号、付款和使用信息，支付数据由 Stripe 处理，服务条款称系统托管在德国。

• 服务可能使用账户信息完成认证、交付、沟通、安全和改进。
• 用户可按适用法律请求访问、更新或删除个人信息。
• 平台声明采用组织和技术措施，但不保证所有风险都能消除。
• 服务不按 HIPAA、FISMA 等行业专项法规设计，受监管团队应谨慎。
• GitHub 仓库、API 设计和生成代码可能包含商业机密，应先完成供应商审查。

隐私页没有充分解释 AI Code Assistant 使用的模型供应商、代码保留期和训练用途。接入私有仓库前，应向销售确认数据处理协议、子处理方、备份删除和模型数据政策。

条款、版权与商用限制

条款允许在合规情况下将服务用于内部业务目的，并保留平台代码、数据库、设计和品牌的权利。平台不是开源代码库，付费订阅不等于可以复制或转售其服务。

• 用户应确保上传的 API、代码和内容拥有必要权利。
• 直接提交的建议可能按条款转让给运营方，发送机密创意前应评估。
• 公开贡献可能授予范围广泛的使用许可，不应把私有设计放入公共区域。
• 服务可发生变更、中断或终止，团队需要导出关键规范并自行备份。
• 条款适用丹麦法律，跨地区企业应评估合同与数据责任。

平台、API 与开源状态

适合用户与场景

• 后端团队：在实现前统一资源、Schema、错误和版本规则。
• 前端与移动团队：用 Mock Server 提前开发和验证界面。
• 产品经理：跟踪接口计划、评审问题与负责人。
• 平台工程团队：维护多个内部和外部 API 的一致性。
• 技术负责人：审查 Baseline 差异并控制破坏性变更。
• 使用 GitHub 的团队：按现有代码样式生成可评审的样板实现。

优势与能力边界

主要优势

• 将 API 设计、Mock、协作、变更记录和代码生成放在同一工作流。
• 可视化编辑降低非后端角色参与接口评审的门槛。
• Baseline 让端点和 Schema 差异更直观。
• Code Assistant 以仓库示例和配置约束输出风格。
• 30 天全功能试用适合真实团队验证。

主要限制

• AI 生成代码仍需评审、测试和安全检查。
• 至少三席的 Team 计划不适合只需一个账号的个人。
• Mock Server 不能替代真实后端测试。
• 未公开模型供应商、代码处理细节、平台 API 和源码。
• 服务不为特定高监管框架量身设计。
• 文档仍标注为持续完善，部分边界可能需要向支持确认。

常见问题

DocDriven 是界面设计工具吗？

不是。它设计的是 API 端点、请求、响应和数据模型，并帮助前后端围绕接口契约协作。

试用期需要信用卡吗？

不需要。30 天试用提供单一工作区和全部功能，结束后不付费会暂停账户。

Team 计划最低需要几个人？

当前页面规定至少 3 名付费用户，另可邀请无限访客。实际总价应在结算页确认。

能导入现有 OpenAPI 吗？

可以从现有 OpenAPI 规范创建项目。导入后仍要检查自定义扩展、安全定义和复杂模型。

Mock Server 可以当生产后端吗？

不可以。它用于模拟设计、前端并行开发和契约测试，不具备生产业务逻辑与数据保证。

AI 会直接改主分支吗？

输出方式可配置为 Pull Request、当前分支或其他分支与仓库。生产团队应使用受保护分支和强制审查。

生成代码会遵循团队规范吗？

Code Assistant 会参考配置文件和示例代码，但仍可能偏离规则。必须运行格式化、测试和人工评审。

DocDriven 是开源的吗？

不是可确认的开源产品。支持 OpenAPI 和 GitHub 集成不代表平台源代码开放。

有公开平台 API 吗？

当前未发现面向普通开发者的 DocDriven API 或 SDK。需要自动化时应先向产品团队确认。

适合医疗或高度监管数据吗？

条款明确服务并非为部分行业专项法规设计。涉及受监管接口或代码时，应完成合规和合同审查后再接入。

总结

DocDriven 适合希望在编码前建立共享 API 契约，并通过 Mock、差异追踪和 AI 样板代码减少协作成本的团队。购买前应重点验证 GitHub 权限、模型数据政策、最低席位和导出备份流程。