接口文档的维护

背景

接口文档是前后端分离后依赖的主要证据。不知道我们的技术经理确定了前端定接口的规则,然而落实到行动上一直后端在维护更新。而且我们的接口文档跟代码是分离的,维护在项目对应的wiki中,这就非常容易容易出现不一致的情况,改了文档忘记改代码或者改了代码忘记改文档,当然大多数是后者。其实即使文档是写在代码的注视里生成JavaDoc也会出现不一致,很多人并不会勤于修改接口文档,代码改爽改通了直接提交合并。

问题

接口文档需要在开发的整个过程中被维护,主要是以下三个阶段

前后端分别开发时, 初步定接口的时候

后端开发完进行文档更新

遇见bug需要修改返回值的时候

一般是2和3阶段,更多的是3阶段容易出现忘记更新文档,从而导致前端依照错误的文档进行开发,而后在测试的时候暴露问题,如果不幸这个问题没有被发现并且上线之后引起问题,这个可就更惨了。

对策

老实说,我是没想到什么好的对策,只能高提高个人素养和觉悟,每次有代码修改时记得去维护它的文档,我想应该有不少人吃过注释文档和代码不一致的苦,不让自己成为未来某个时候接锅者吐口水的对象

  • 发表于:
  • 原文链接http://kuaibao.qq.com/s/20180318G0LKXZ00?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券