约束

假如你的项目中有若干前端和若干后端。你现在需要开发一个登陆接口，通常情况下这个功能一个前端和一个后端开发就足够了。有些公司的后端很强势，因此可能出现后端写好接口之后告诉前端去开发页面。也可能前端很强势，因此前端写好页面之后让后端去写接口。
这两种情况都不是我们希望见到的。这是因为如果我们自由开发一个接口，后端开发人员通常会选择最符合后端直觉的方式去写接口。反过来，对于前端开发人员来说，他们一定会选择最容易展示的方式去写页面。这两种直觉之间是会有差异的，因此这样的一方主导开发的情况很容易出现各种各样的意外情况。
所以为了避免这样的情况，我们需要接口文档来约束前后端的协同开发。

规范

虽然现在前后端分离居多，但是如果我自己一个前后端都可以做，肯定会了解前后端各自的特点，就不会因为开发思路的差异而导致出现意外。那么对于我来说，是不是接口文档就没必要存在了呢？
答案显然是否定的。接口文档的另一个重要作用就是规范。
项目需求变动是很常见的情况，举个例子，我们现在有一个学生表。页面上需要用一个表格展示所有的学生，可以分页操作。
假设现在的接口文档是这样的：

然后需求变动了，我们需要把学生表展示为教师表。

这两个接口从后台逻辑来说应该是完全一致的。唯一的差别是我们需要查不同的表。从前台逻辑来说，这两个除了接口不一样，其他的分页字段应该是一致的。理想情况下如果一个前端开发接手这个页面之后，完全可以不看文档直接改API地址，然后修改页面的填充数据就可以了。
现实是，很多接口的规范做的不好。这就导致了，逻辑相同的两个接口，他们的查询参数可能是不一样的。这样就会出现下面的情况：

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

版本回溯

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

总结

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