接口文檔在項目中的做用

先後端合做開發的時候常常須要用到接口文檔，那麼接口文檔在產品中究竟有什麼做用？該如何去規範呢？

約束

假如你的項目中有若干前端和若干後端。你如今須要開發一個登錄接口，一般狀況下這個功能一個前端和一個後端開發就足夠了。有些公司的後端很強勢，所以可能出現後端寫好接口以後告訴前端去開發頁面。也可能前端很強勢，所以前端寫好頁面以後讓後端去寫接口。
這兩種狀況都不是咱們但願見到的。這是由於若是咱們自由開發一個接口，後端開發人員一般會選擇最符合後端直覺的方式去寫接口。反過來，對於前端開發人員來講，他們必定會選擇最容易展現的方式去寫頁面。這兩種直覺之間是會有差別的，所以這樣的一方主導開發的狀況很容易出現各類各樣的意外狀況。
因此爲了不這樣的狀況，咱們須要接口文檔來約束先後端的協同開發。

規範

雖然如今先後端分離居多，可是若是我本身一個先後端均可以作，確定會瞭解先後端各自的特色，就不會由於開發思路的差別而致使出現意外。那麼對於我來講，是否是接口文檔就不必存在了呢？
答案顯然是否認的。接口文檔的另外一個重要做用就是規範。
項目需求變更是很常見的狀況，舉個例子，咱們如今有一個學生表。頁面上須要用一個表格展現全部的學生，能夠分頁操做。
假設如今的接口文檔是這樣的：

而後需求變更了，咱們須要把學生表展現爲教師表。

這兩個接口從後臺邏輯來講應該是徹底一致的。惟一的差異是咱們須要查不一樣的表。從前臺邏輯來講，這兩個除了接口不同，其餘的分頁字段應該是一致的。理想狀況下若是一個前端開發接手這個頁面以後，徹底能夠不看文檔直接改API地址，而後修改頁面的填充數據就能夠了。
現實是，不少接口的規範作的很差。這就致使了，邏輯相同的兩個接口，他們的查詢參數多是不同的。這樣就會出現下面的狀況：

返回內容的更改是沒問題的，可是由於兩個接口沒有規範，這就致使其餘開發人員接手的時候不只須要改數據的格式，也須要更改參數名。這在無形中就下降了開發效率。
另外一方面，文檔健全確定是好的。可是毫無規律，隨意編寫的文檔卻會下降開發效率。所以健全的文檔必需要配合良好的文檔規範，這樣纔可讓開發人員能夠預估API返回的數據格式和請求參數。

版本回溯

基本上每一個遊戲都有一個版本號。這個版本號是代碼的版本，表示這個版本的代碼有相應的功能。一樣的道理，文檔也須要經過版本進行管理。每一個版本的API都要有相應版本的接口文檔。這樣當項目須要回滾的時候咱們能夠立刻知道上個版本的需求。

總結

本文沒有從教科書的層面去說項目文檔的做用，我是結合了本身的開發經驗來講一下本身對文檔的體會。最後是推一下我常常用的接口文檔工具Eolinker，集成化不用多個接口工具一塊兒使用，Saas忽然換電腦也不用從新部署，相比其餘的方便不少。
使用地址：www.eolinker.com