接口文档编写规范和示例

API接口文档的编写已不是什么新鲜事，但文档的编写有时还需针对看文档的人，有所侧重。大多数时候我编写API文档都是针对前台开发、或是后台开发，简单明了就好。

记得有次公司商务说让我给写几个接口的文档，他给我几点要求：

有几个接口，分别是什么？（例如XX信息下发接口、XX信息更新接口、XX信息反馈接口）

每个接口的作用是什么，传递了哪些信息？（例如XX信息反馈接口传递的具体信息内容主要包括：信息 ID 号、信息接收时间、信息展示时间、信息发布情况…….。）

1. 需求背景

SRM系统的用户，需要在SRM查看自己提供的商品的质检情况；但是质检的数据在商品管理系统中，故需要SRM从商品管理系统获取对应的数据

2. 需求设计

需求关键点是SRM需要从商品管理系统获取数据并展示给自己用户，实现这一点有两种方式：

（1）SRM固定频次从商品管理系统获取

选择这种方式，有一个绕不开的问题：什么时候去取数据合适？普遍的自然就想到按固定的频率，那么这个频率应该是什么？

考虑到用户随时都会点击查看，半小时、一小时的频率肯定不行；实时性应该越高越好，那半分钟或者1分钟取一次呢？

这样做相比半小时实时性高了很多，但考虑到数据量的因素，虽然每分钟会去获取，但是获取到数据后进行合法性校验、完了组装存储，整个周期就远不是1分钟了，有可能用户点击的时候，数据刚获取到，还没处理完存储到表中，故也无å法展示；

同时，随着数据量增大，此种情况下很容易出现漏数据和数据重复的情况，数据量太大，程序执行时间过长而自动停止，导致数据遗漏，第一次还没处理完，第二次已经开始了，结果相同的数据多次写入，导致数据重复。

故此种方式不可行。

（2）商品管理系统主动同步

既然自己取不可行，那么商品管理系统主动将数据同步到SRM呢？

当商品管理系统的质检信息有变更时，主动将数据同步给SRM，用户在SRM查看的时候，SRM从自己的表中获取数据并展示，这样看这种方案是完全能够满足要求的。

我一开始做的时候，也是选择的这种方案，但是在与开发沟通的时候（一般做接口更偏向技术，所以我都事先会跟开发私下讨论一下），发现有一个问题：相同的信息有没有必要在两个系统存储两份？因为质检信息中存在附件文件，文件很占存储空间。是否有更好的方案来避免这个缺陷？

结合上面这两个分析，我们知道这个接口有两个点很重要：

实时性要求极高；能共用一份信息就不存两份。基于实时性要求高这个点，为什么不做成用户查看的时候，实时去商品管理系统获取数据并展示出来呢？这样也解决了SRM不用存储冗余信息的问题。

为此此需求最佳的方案是：当用户在SRM点击查看的时候，SRM实时去商品管理系统获取质检信息并展示，无需本地保存：

PS：实时获取有一个隐形的问题是：并发。若并发量高，实时获取的方式不可取。但此业务中，并发可能性低，所以此方案可行最优。

上文就是小编为大家整理的接口文档编写规范和示例。

国内(北京、上海、广州、深圳、成都、重庆、杭州、西安、武汉、苏州、郑州、南京、天津、长沙、东莞、宁波、佛山、合肥、青岛)API接口文档平台软件分析、比较及推荐。