网页内 API 参考页面逐项说明
网页内 API 页面是面向访问者的交互式参考索引。它适合查看公开接口的路径、方法、请求参数和响应字段；真正开发时仍应结合文档站的版本化专题页。
页面结构
页面可能包含：
- API 基础地址提示；
- 分类折叠区；
- 分类说明；
- 接口卡片；
- 请求方法和路径；
- 请求参数表；
- 响应字段树；
- 复制按钮；
- 版本/免责声明说明。
页面是只读参考，不会因为展开分类而调用接口。复制代码时仍要检查是否包含占位符和敏感字段。
接口分类
公开页面可能按以下主题组织：
- Token 认证；
- 访问码和二维码；
- 配方管理；
- 相片；
- 普通缓存；
- 上传缓存；
- 用户乐曲数据；
- 成绩互动；
- 游玩记录；
- 查卡；
- 地区统计；
- 服务统计。
分类是否显示受当前版本影响。隐藏分类不应被客户端猜测或补齐。
折叠分类
点击分类标题展开/收起：
- 展开只改变当前页面状态；
- 不会提交 Token；
- 同一时间可以打开多个分类；
- 页面离开后折叠状态可能重置；
- 折叠不代表接口不可用。
移动端使用时先展开一个分类，避免在长页面中误点其它按钮。
接口卡片
每张接口卡片可能显示：
- 名称；
- HTTP 方法；
- 相对路径；
- 用途说明；
- 是否需要 Token；
- 请求参数表；
- 响应字段表。
卡片显示的字段属于公开参考。若网页页面和文档专题描述不同，以当前服务响应和最新文档为准，并记录版本。
请求参数表
参数表通常有：
- 参数名；
- 类型；
- 必填/可选；
- 说明。
可选字段留空和发送空字符串不是同一行为。开发者不要把所有可选字段都发送为空值，除非专题页明确如此要求。
请求体中的 Token、密码、访问码、目标标识和文件名都应在客户端日志中脱敏。
响应字段树
嵌套对象可以展开查看子字段。字段树用于理解结构，不代表字段一定在每次响应中存在：
- 可选字段可能缺失；
- 空数组和 null 有不同语义；
- 文件接口可能返回二进制；
- 未知字段应保留；
- 枚举值可能随版本增加。
不要仅依据响应字段顺序或示例值写客户端解析。
复制按钮
复制按钮可能复制 JSON、请求示例或字段路径。复制后：
- 检查是否仍有占位符；
- 确认没有真实凭据；
- 放入受保护代码或临时编辑器；
- 使用后清理剪贴板。
不要把复制结果直接粘贴到公开群或工单。
API 基础地址
页面可能显示默认基础地址和版本路径。客户端应把基础地址作为配置，而不是在多个文件中硬编码。自定义地址只有在页面和管理员明确允许时使用。
错误页面与兼容性
网页 API 参考本身加载失败时，分开判断：
- 文档站页面是否可加载；
- API 服务是否可达；
- 当前账号是否有权限；
- 接口响应是否符合公开结构。
API 页面可打开不证明接口当前可调用；接口返回 403 也不证明文档页面损坏。
使用页面建立客户端
推荐顺序：
- 从 API 概述确认统一请求规则；
- 在专题页确认端点和业务约束；
- 在公开字段目录确认类型；
- 在工作流页确认先后关系；
- 在错误/分页/兼容性页确认失败处理；
- 使用占位数据编写测试；
- 先做只读请求，再开放写入。
不要把网页内 API 页面当作未记录接口的入口目录，也不要调用页面没有展示的路径。
页面验收清单
- [ ] 所有公开分类可以展开/收起；
- [ ] 路径、方法和参数可读；
- [ ] 嵌套响应字段可展开；
- [ ] 复制按钮不泄露生产值；
- [ ] 移动端长表格可滚动；
- [ ] 代码示例使用占位符；
- [ ] 页面离开不会发起接口调用；
- [ ] 搜索/导航回到正确专题页。