接口文档在项目中的做用

先后端合做开发的时候常常须要用到接口文档，那么接口文档在产品中究竟有什么做用？该如何去规范呢？

约束

假如你的项目中有若干前端和若干后端。你如今须要开发一个登录接口，一般状况下这个功能一个前端和一个后端开发就足够了。有些公司的后端很强势，所以可能出现后端写好接口以后告诉前端去开发页面。也可能前端很强势，所以前端写好页面以后让后端去写接口。
这两种状况都不是咱们但愿见到的。这是由于若是咱们自由开发一个接口，后端开发人员一般会选择最符合后端直觉的方式去写接口。反过来，对于前端开发人员来讲，他们必定会选择最容易展现的方式去写页面。这两种直觉之间是会有差别的，所以这样的一方主导开发的状况很容易出现各类各样的意外状况。
因此为了不这样的状况，咱们须要接口文档来约束先后端的协同开发。

规范

虽然如今先后端分离居多，可是若是我本身一个先后端均可以作，确定会了解先后端各自的特色，就不会由于开发思路的差别而致使出现意外。那么对于我来讲，是否是接口文档就不必存在了呢？
答案显然是否认的。接口文档的另外一个重要做用就是规范。
项目需求变更是很常见的状况，举个例子，咱们如今有一个学生表。页面上须要用一个表格展现全部的学生，能够分页操做。
假设如今的接口文档是这样的：

而后需求变更了，咱们须要把学生表展现为教师表。

这两个接口从后台逻辑来讲应该是彻底一致的。惟一的差异是咱们须要查不一样的表。从前台逻辑来讲，这两个除了接口不同，其余的分页字段应该是一致的。理想状况下若是一个前端开发接手这个页面以后，彻底能够不看文档直接改API地址，而后修改页面的填充数据就能够了。
现实是，不少接口的规范作的很差。这就致使了，逻辑相同的两个接口，他们的查询参数多是不同的。这样就会出现下面的状况：

返回内容的更改是没问题的，可是由于两个接口没有规范，这就致使其余开发人员接手的时候不只须要改数据的格式，也须要更改参数名。这在无形中就下降了开发效率。
另外一方面，文档健全确定是好的。可是毫无规律，随意编写的文档却会下降开发效率。所以健全的文档必需要配合良好的文档规范，这样才可让开发人员能够预估API返回的数据格式和请求参数。

版本回溯

基本上每一个游戏都有一个版本号。这个版本号是代码的版本，表示这个版本的代码有相应的功能。一样的道理，文档也须要经过版本进行管理。每一个版本的API都要有相应版本的接口文档。这样当项目须要回滚的时候咱们能够立刻知道上个版本的需求。

总结

本文没有从教科书的层面去说项目文档的做用，我是结合了本身的开发经验来讲一下本身对文档的体会。最后是推一下我常常用的接口文档工具Eolinker，集成化不用多个接口工具一块儿使用，Saas忽然换电脑也不用从新部署，相比其余的方便不少。
使用地址：www.eolinker.com