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檔案，可以更快的熟悉專案，儘早完成任務。