一個簡單的接口文檔，寫完給組長看后，發現漏洞百出。下面總結一下寫文檔需要注意事項：
封皮
封面最好是本公司規定的封面，有logo，內容標題，版本號，公司名稱，文檔產生日期。（錯誤地方在於，文檔的標題要和頁眉中的標題一致）
eg: 電信查詢專用系統二期號碼詳單查詢接口規范（主要看單位的要求）
修訂歷史
表格形式較好些。包括，版本，修訂說明，修訂日期，修訂人，審核時間審核人。（我錯誤的地方在於，表格中其他空白表格沒有居中）
eg:嘻嘻嘻我的文檔里沒有這個
接口信息
接口調用方式，是post方式還是get方式，接口地址，別人需要線上的哪個地址就寫哪個。（自己提前測試好線上的這個接口，是否有其他問題，千萬別犯低級的錯誤，尤其是某個字母寫錯）
eg:（這個可以空着 讓前端定格式，你完成就好了）
圖中就是post請求 主機地址 132.90.101.139 接口地址59637
中間遇到的問題：springboot @RequestMapping注解
功能描述
一定要清晰的描述接口功能。（不要遺漏一些細節，比如接口獲取的信息不包括哪些哪些要寫明白）
接口參數說明
每個參數都要和實際中調用的一樣，包括大小寫；參數的含義言簡意賅的說明；格式，是string 還是int 還是long等格式（例如參數為@RequestParam("appKey") String appKey, @RequestParam("randomId") Integer randomId）；說明部分，說明參數值是需要哪個公司提供，並詳細說明參數怎么生成的，例如時間戳，是哪個時間段的；參數是否必填，一些參數是必須要有的，有些是可選參數，一定要注意寫清晰。
返回值說明
1、有一個模板返回值，並說明每個返回參數的意義。
2、提供一個真實的調用接口，真實的返回值。
接口調用限制，接口調用安全方面
為了接口安全，我們可以進行md5加密方式，或者自己公司一個特殊的加密過程，只要雙方采用一致的加密算法就可以調用接口，保證了接口調用的安全性。
文檔全局方面
文檔大標題的字體字號一致，小的分標題一致，正文部分字號也要一致。文章整體字的類別一致，我認為微軟雅黑字體樣式給人感覺比較清晰。文檔目錄，自動生成的目錄會添加些許的修飾，去掉不整齊的部分，得到一個整齊的目錄格式。
文檔維護
文檔在維護的時候，如有修改一定要寫上修改日期，修改人，對大的修改要有版本號變更。
好文檔標准檢驗
我認為檢驗一個文檔寫的是否好，主要還是在內容方面，內容是否仔細沒有疏漏之處。是否發給別人使用的時候，無需溝通就能把接口調通。別人通過成功的把接口調通，這就是一個好文檔。
總結
雖然對於敏捷開發來說項目不需要需求，設計，詳細設計等文檔，但是在和別的公司在調用接口的時候，是一定要總結成文檔的，形成接口規范，文檔規范。昨天看到微信分享的一篇文檔，叫做《教養，就是讓別人舒服》，我想在寫文檔的時候，把自己當做看文檔的人，怎么寫讓別人舒服，我想這就是寫文檔的“教養”吧。
————————————————
版權聲明：本文為CSDN博主「永遠的晴天」的原創文章，遵循 CC 4.0 BY-SA 版權協議，轉載請附上原文出處鏈接及本聲明。
原文鏈接：https://blog.csdn.net/lovesummerforever/article/details/45149393