Skip to content

API 文档系统

字数
420 字
阅读时间
2 分钟

说明

一个能够追踪 API 响应对象中的字段在「什么时候」、「什么版本」、「什么提交」里面新增或者发生变更,甚至是提供即将废弃的注解。

在开发的时候期间,Staging 过渡阶段,FAT 特性验收测试阶段,UAT 用户可接受度测试阶段是没办法很好的记录到版本号的,可能得根据提交记录和提交时间来完成,否则开发者得把 API 版本和后端版本剥离,并分别进行记录。不过在我看来,记录版本号、剥离版本号并记录的任意一种方案,甚至是记录提交这类的事情不应该是 API 接口开发者应该做的,应当在 API 定义发生变更之后由 API 文档系统自动变更版本号并且在文档中正确渲染和提示到使用用户。

可能的情况下,该系统甚至能提供一些 DevOps 联动,在必要的情况下可以允许文档系统提示该字段所处的阶段,比如能展示到 Staging 阶段或者是 Production 阶段。

可能的情况下,该系统还应该提示 beta / experiment API 注解高亮说明,并建议「为生产产品开发的开发者:尽可能避免使用正处于 beta / experiment 的 API,这些 API 可能随时发生变更,暂时不稳定,并采用其他替代方案实现」。

贡献者

文件历史

撰写