和朋友聊天，他說他們公司開始了一個新項目，由他負責后端開發。因為之前做過全棧的項目，前后端開發思路都懂，就自己把邏輯走了一遍，寫了api接口。結果項目開發到一半，新招了個ios，上來就說他寫的接口不行吵了起來。
那么接口文檔到底是該誰來定義呢？
接口是什么？
API，全稱是ApplicationProgramming Interface，即應用程序編程接口，我們日常中習慣簡稱為“接口”。接口是一些預先定義的函數，目的是提供應用程序與開發人員基於某軟件或硬件的以訪問一組例程的能力，而又無需訪問源碼，或理解內部工作機制的細節。
接口有什么用？
在平時的開發過程中，前后端經常會進行數據交互，那么在前后端分離的項目中，前端就不用管后台的工作，用api調取數據即可。
接口文檔該由誰來寫呢？
筆者認為一般接口文檔一定是后端來寫，只是我們要事先要和前端商量定義，然后再編寫接口文檔，之后大家都根據這個接口文檔進行開發，到項目結束前都要一直維護。
通俗一點就是：客戶端出接口需求，服務端出接口方案。
為什么要寫接口文檔？
1、項目開發過程中前后端工程師有一個統一的文件進行溝通交流開發；
2、項目維護中或者項目人員更迭，方便后期人員查看、維護；
接口規范是什么？
首先接口分為四部分：方法、url、請求參數、返回參數
1、方法:新增(post) 修改(put) 刪除(delete) 獲取(get)；
2、url：uri地址里不允許出現大寫字母，如果是兩個單詞拼接，用/分開；
3、請求參數和返回參數，都分為5列：字段、說明、類型、備注、是否必填；
4、返回參數結構可以有一個結構體也可以有多個結構體；
如何自動生成文檔？
最簡單的是找一個合適的工具，省去敲字對格式的痛苦。這里推薦的是Eolinker，一個適合不同規模開發團隊的在線API文檔工具。而且除了文檔部分的功能外，整個API開發流程的不同階段，都可以直接在Eolinker上進行，省事。
當然還有其他類似的平台也可以滿足在線編輯規范接口的平台：apidoc，sosoapi等
使用地址：www.eolinker.com