前后端合作開發的時候經常需要用到接口文檔，那么接口文檔在產品中究竟有什么作用？該如何去規范呢？
約束
假如你的項目中有若干前端和若干后端。你現在需要開發一個登陸接口，通常情況下這個功能一個前端和一個后端開發就足夠了。有些公司的后端很強勢，因此可能出現后端寫好接口之后告訴前端去開發頁面。也可能前端很強勢，因此前端寫好頁面之后讓后端去寫接口。
這兩種情況都不是我們希望見到的。這是因為如果我們自由開發一個接口，后端開發人員通常會選擇最符合后端直覺的方式去寫接口。反過來，對於前端開發人員來說，他們一定會選擇最容易展示的方式去寫頁面。這兩種直覺之間是會有差異的，因此這樣的一方主導開發的情況很容易出現各種各樣的意外情況。
所以為了避免這樣的情況，我們需要接口文檔來約束前后端的協同開發。
規范
雖然現在前后端分離居多，但是如果我自己一個前后端都可以做，肯定會了解前后端各自的特點，就不會因為開發思路的差異而導致出現意外。那么對於我來說，是不是接口文檔就沒必要存在了呢？
答案顯然是否定的。接口文檔的另一個重要作用就是規范。
項目需求變動是很常見的情況，舉個例子，我們現在有一個學生表。頁面上需要用一個表格展示所有的學生，可以分頁操作。
假設現在的接口文檔是這樣的：
然后需求變動了，我們需要把學生表展示為教師表。
這兩個接口從后台邏輯來說應該是完全一致的。唯一的差別是我們需要查不同的表。從前台邏輯來說，這兩個除了接口不一樣，其他的分頁字段應該是一致的。理想情況下如果一個前端開發接手這個頁面之后，完全可以不看文檔直接改API地址，然后修改頁面的填充數據就可以了。
現實是，很多接口的規范做的不好。這就導致了，邏輯相同的兩個接口，他們的查詢參數可能是不一樣的。這樣就會出現下面的情況：
返回內容的更改是沒問題的，但是因為兩個接口沒有規范，這就導致其他開發人員接手的時候不僅需要改數據的格式，也需要更改參數名。這在無形中就降低了開發效率。
另一方面，文檔健全肯定是好的。但是毫無規律，隨意編寫的文檔卻會降低開發效率。因此健全的文檔必須要配合良好的文檔規范，這樣才可以讓開發人員可以預估API返回的數據格式和請求參數。
版本回溯
基本上每個游戲都有一個版本號。這個版本號是代碼的版本，表示這個版本的代碼有相應的功能。同樣的道理，文檔也需要通過版本進行管理。每個版本的API都要有相應版本的接口文檔。這樣當項目需要回滾的時候我們可以馬上知道上個版本的需求。
總結
本文沒有從教科書的層面去說項目文檔的作用，我是結合了自己的開發經驗來說一下自己對文檔的體會。最后是推一下我經常用的接口文檔工具Eolinker，集成化不用多個接口工具一起使用，Saas突然換電腦也不用重新部署，相比其他的方便很多。
使用地址：www.eolinker.com
