V2 场景切入 / 基于 Landing Page Variants Overview 与 Build Spec 实现

每次合并 PR 前,
先知道 API 改了什么。

当代码或 OpenAPI 变更时,系统自动检测接口差异、识别 breaking changes、生成版本建议与 changelog,让后端、前端、SDK 和外部集成方不再在过时文档上继续开发。

~/pull-request-impact
$ api-diff check origin/main...feature/auth-refresh

 OpenAPI diff completed
 6 endpoint changes classified
! 2 breaking changes detected

# impact summary
- PATCH /users/{id} response removed field: timezone
- POST /tokens/refresh request body schema changed
- GET /projects added optional filter: archived

# release suggestion
recommended version: v2.4.0 → v3.0.0

# output
changelog.md generated
sdk-notice.md generated
frontend-impact.md generated
Problem / Benefit Strip

真正危险的不是 API 改了,而是有人根本不知道它已经改了。

这次页面按 spec 采用 V2 场景切入:不是卖“文档工具”,而是卖“合并前的风险可见性”。它解决的是 PR 已 merge、联调才炸、外部集成方还在用旧文档的那种低级但昂贵的问题。

Scene 01

在 PR 阶段看到这次接口变更会影响谁。

系统在 repo 或 OpenAPI diff 层自动识别改动范围,先告诉你这是不是 breaking change,再告诉你谁会被波及,而不是等 QA、前端或客户来替你发现。

Merge 之前就有影响面

把“接口改了没”从口头同步,变成可见、可追踪、可落日志的工程信号。

Scene 02

不再手工补 changelog,也不再赌文档会有人记得更新。

变更日志依赖人工补写这件事,本身就注定会漏。这个产品把差异检测、版本建议、日志生成连成一条自动化链路。

检测 → 版本建议 → changelog

收益不是“多一个文档页面”,而是 API 演进终于能按工程化方式被管理。

Workflow Demo / Build Spec Section 3

Repo → diff → rule engine → changelog → release,一条线讲清楚。

读取代码与 OpenAPI 结构

支持从 repo、spec 文件或 CI 产物中抽取接口快照,建立 before / after 版本基线。

分类变更等级

breaking、non-breaking、docs-only 分开处理,避免所有改动都被粗暴地算成同一类。

before: POST /tokens/refresh
body.refreshToken: string

after: POST /tokens/refresh
body.sessionToken: string

impact: breaking

输出多视角产物

不仅生成 changelog,还能同步产出 frontend-impact、SDK notice、release note 和 PR comment,让不同角色看到自己需要的信息。

Change Classification / Impact

至少三类示例,直接让团队理解“这次变更严重到什么程度”。

3
breaking / non-breaking / docs-only,严格对应 build spec 的示例要求
1
推荐版本建议链路,把技术差异直接翻译成版本动作
PR
把文档治理前移到合并前,而不是事故发生后
Breaking example

字段删除、Schema 变化、路径语义改变,都应该被高亮成阻断信号。

例如 response field 被移除、request body 强制字段改变、枚举值废弃但未保留兼容层,这些不该只写进 commit message。

不是记录改动,而是判断风险

Spec 里明确要求把 change classification 做成可读示例,这里就按规则直接展示“差异 + 影响 + 建议版本”。

FAQ

这不是完整 API 管理平台,而是专注在变更检测与版本治理的前置层。

它只支持 OpenAPI 吗?

首版可以从 OpenAPI 入手,但核心价值其实是差异识别与版本产物生成,未来可接更多接口描述来源。

没有真实截图怎么办?

Build Spec 明确允许在真实产品截图未就绪前使用高保真示意图与占位 UI,所以当前页面按这个原则实现。

为什么 CTA 是“申请演示 / 获取接入指南”?

这也是 Build Spec 里给定的主次 CTA 方向,适合早期 DevTool 产品先验证高意向团队。

需要追踪哪些事件?

已按 spec 植入通用 GA4 / GTM,核心事件方向包括 hero CTA、secondary CTA、FAQ 展开和表单成功/失败。

Primary CTA

别再让前端、SDK 或客户替你发现 API 已经变了。

申请演示,或者先获取接入指南。让每次 PR 合并前的接口变化,都有明确分类、影响说明和版本化 changelog。

姓名
工作邮箱
公司 / 团队
当前 API 文档方式 / 月度 API 变更频率