api文件編寫好像很簡單，其實不是。
一個良好的api文件，需要就有以下內容：
介面詳細描述，介面引數詳細描述，介面返回結果詳細描述，容易理解的範例。這些內容其實是不少的，編寫過程中還非常單調乏味。再加上專案緊張，積壓的未編寫api文件太多等等因素，造成了現實工作中，大部分api文件都是殘缺不全的狀況。從結果上看，編寫api文件並不簡單。
api文件編寫好像只是後端工程師一個人的事情，其實不應該是。
實際工作中，api文件都是由實現這個api的後端工程師根據api來編寫的。因為api是某人開發的，他知道最清楚，api文件就應該是這個人來寫。大家都是這麼理所當然的認為。但是這個介面不是後端工程師無中生有自己造出來的，而是大家根據需求討論確定的。這個介面的功能、請求引數、返回結果，都是根據需求來確定的。不止和後端工程師關係密切，和產品人員、經理、前端人員都有關係，後來者也要根據這些api文件來工作。因此api文件編寫不只是後端工程師一個人的事情。
api文件不要一個人完成，這樣他的負擔會很重，尤其是後端開發人員。我們應該是這樣做：產品新建介面，填寫部分內容，主要是介面名稱和描述；後端開發人員編寫介面的url、介面引數和返回欄位；前端人員參與確定和編寫部分api文件內容；技術經理從全域性角度審查和編寫部分api文件。
api文件應該儘早編寫。
api文件是前後端開發人員協作的依據。沒有api文件，前端開發人員就無法進行開發，專案也就無法推進。
傳統的做法是：大家一起開需求會；開完需求會議後，後端開發人員花一段時間實現介面；為了讓前端人員能儘快使用介面，後端開發人員會盡快簡單編寫一下api文件，再通知前端開發；前端開發人員再按照api文件開發程式，繫結資料；最後前後端人員一起聯調。
這樣單向的，一步一步依次執行的工作模式，像鏈條一節連著一節。即使其中某一個人工作高效，完成迅速，也難以加快專案整體的進度；相反，只要其中一個環節卡住了，整個專案也就停止了，上線變成不可能。總的結果是，讓專案難以快速完成，上線時間非常緊張。
參與專案開發的所有都感覺到了這一模式的缺陷。
我們應該以api文件為中心展開工作。
首先，需要改進工序。
一，產品人員在調研需求，完成原型之後，應該整理一下每個頁面，每個功能大概需要哪些介面，新建api文件，填寫部分內容，包括介面名稱，介面描述，返回的結果欄位描述。
二，召集所有人員參加需求會，講解需求，分配模組開發人員，討論介面文件中哪些可以當場確定。
三，負責相同模組的前後端人員一起討論，根據已經建立的api文件，確定api的url，請求引數名稱，返回結果欄位名稱，完善好api文件；api文件的所有內容都應該完全確定，如果有疑問，應該找產品人員和經理一起確定。
四，前後端人員嚴格依照api文件各自開發，如果開發過程中有變動，一定要通知對方，並且修改api文件。這樣兩人同時進行開發，實現了並行工作，比老的api和文件完成後再做前端節約了大量時間。
五，前後端人員實現功能後進行聯調，如果出現分歧，應該以api文件為基準。
以api文件為中心，儘快確定api文件和詳細引數及結果，儘早完善文件，還有利於新人接收。新接手人蔘照完善的api文件，可以更快的熟悉專案，儘早完成任務。