API 参考页别按模块拆，按用户任务拆

API 文档的信息架构，决定了你的文档能吃到多少搜索流量。2025 年 3 月我们重做一个支付 API 的文档站，原本 210 个端点塞在 12 个按模块分的页面里，全部内容只有 12 个 URL。改成“一个端点一个页面”后，六个月自然流量涨了 1.4 倍，被 AI 回答引擎引用的次数从每月个位数到四十多次。

按模块拆为什么不好

模块是开发者的分类，不是搜索者的语言。用户搜的是“创建退款”“查询结算批次”“取消订阅”，不是“结算模块 API 参考”。按模块拆的页面，一个 URL 里混着八到十个端点，title 只能写成模块名，页面里每段都浅，排名上不去。

更要命的是锚点没法被当作独立结果。用户搜“stripe 创建退款接口”，搜索结果的标题是“退款 API”，描述里是整段模块说明，点击率低。拆开之后标题能写“创建退款 - 退款接口 v2”，点击率差别很大。

拆页的三条规则

第一，按“用户要做的事”命名。URL 用动词加对象：/api/create-refund、/api/list-settlements，不要用 /api/refund-endpoint-v2。标题用中文任务名加版本，别用英文函数名做主标题。

第二，一个端点一页，但相同语义的批量接口合并。比如查询单个和查询列表，合成一页两个示例。我们拆 210 个端点最后出了 148 个页面，合并的都是这类。

第三，页面结构统一成五段：干什么用、请求参数表、返回示例、错误码、常见问题。参数表用真实默认值，别写“见下文”。

拆分之后要接内链

拆完最容易犯的错是页面之间互不相通。我们的做法是每个页面底部固定放两块：本页相关的上游接口、下游接口各两到三个。比如“创建退款”下面放“查询退款状态”“列退款列表”。这部分我们写了个脚本从 OpenAPI 文件自动生成，省了人工。

还有一个位置别漏：每个端点的“错误码”要链到错误码总表，总表再链回具体端点。这一进一出，把文档站织成网。

哪些页不该单独拆

不是所有端点都值得一个页面。内部调试用的、已废弃的、只在企业版开放的，都不拆，放在一页里说明就行。拆完留下 20 个只有一句话的页面，会稀释整站质量。判断标准很简单：这个端点有没有人会用一句话去搜它。

拆分是工程活，不是内容活。改完之后要盯三个数：索引覆盖、页面平均展示、文档到注册的转化。前两个涨得慢，第三个通常一个月内就能看到变化。