如何編寫優質的API文檔？

在我們平常的工作中，常常要和其他部門進行合作，在這個過程中我們就會用到他們的介面（API），當然我們是不知道他們怎麼定義的，比起一遍遍地去問他們，這個時候，國際通用做法，他們會甩過來一個文檔給我們，那麼既然是人寫的東西，那自然是褒貶不一咯，有的部門的文檔就寫的非常清晰，非常完善，你看了文檔之後，基本上不用再去問對面的人，除非出現了大的問題。那麼如何去寫一個完善的API文檔呢？從現實出發，來談談我在工作中希望看到的文檔有哪些內容吧。


1. 文檔用處，這裡需要簡單的寫出，這個文檔到底是用來做什麼的，目的是什麼，適合哪些人看

2. 在使用過程中 有哪些前提。比如要申請什麼許可權，或者拿到某些授權。諸如這樣的，就是一些base condition

3. 文檔欄位的一些細節。比如介面中需要傳過去多少個欄位，每個欄位的類型，欄位的取值範圍，欄位的含義，欄位傳輸示例。

4. api介面的返回值，返回值的格式要求和3一樣寫明白含義，並且給出樣例返回結果。

5. 介面負責人以及負責人的聯繫方式，辦公地點，這樣方便在有問題的時候可以第一時間聯繫到相關責任人。

6. 一段介面使用的示例，包括請求值和返回值，最好是一段簡單的代碼，當然偽代碼也是可以的。

其實寫好一個文檔是很困難的，在用詞上一定要注意，盡量使用準確的辭彙，不要使用可能，或許，大概這種不定的辭彙，會給閱讀者帶來很大的困惑，標準就是可以讓使用者簡單學會如何快速上手。

---

推薦閱讀：