API文件之團隊協作

api是程式的關鍵，與之對應的api文件也是專案中重要的組成部分。api從設計開始到停用這個過程稱之為api生命週期，而文件的作用貫穿api整個生命週期中的各個階段，讓使用者可以清楚的知道api每個階段的情況。

乙份好的api文件不僅包括api的基本資訊，如url、請求頭部，請求引數等，還包括api的示例等資訊。api文件涉及的點很細，並且不只是開發人員檢視api文件，非技術人員或企業外部使用者也會涉及，這使得api文件的編寫難上加難。

api文件由設計api或進行api開發的人員編寫是最適合的，他們知道api的詳細資訊，所以在編寫上不僅簡單且不容易出錯，但這只對於小團隊有利。當專案達到一定規模或api達到一定數量時，如果還是由開發人員去編寫與維護，則可能造成api文件混亂、難以維護的結果。

既然api文件貫穿api的整個生命週期，那麼是否可以在api的各個階段分不同角色對api進行維護呢?答案是可以的。 api在設計初時即可將api記錄為文件。

設計api的人員確認api的功能與基本資訊後，可記錄在api文件中，並生成迭代計畫，這就是乙個api的開始。

經過確認後生成mockapi，前後端人員分工合作，前端開始使用mockapi進行開發，後端則參考api文件開發api。

開發人員開發完api後替換，新增測試環境host，由測試人員開始測試，並生成測試用例，在此過程中完善api文件。

當確認api在測試環境可以正常使用後，則選擇合適的時間把api更新到正式環境，此時需要通知到響應的人員。

需要對api進行維護時則重複以上過程，直至api棄用，至此api的生命週期結束。在整個過程中，我們把api的不同階段劃分出來，且每個階段由不同的人員進行編寫，這種做法有利於分擔開發人員的工作，且各個階段的人員編寫的文件也是標準、專業的。