前言：
最近看了很多寫的非常好的接口文檔，在理解業(yè)務(wù)方面給了非常多的幫助氧敢，解決很多時候?qū)τ谝恍﹨f(xié)商數(shù)據(jù)的問題困擾日戈，同時，后續(xù)個人的工作當(dāng)中福稳，也需要對外開放接口給第三方進(jìn)行調(diào)用涎拉，這時候一個好的規(guī)范文檔可以解決很多問題瑞侮。
文章目的：
1.個人對于寫接口文檔的一些資料整理。
2.學(xué)習(xí)如何寫一份別人樂意去看的文檔鼓拧。
3.希望可以通過本文幫助處理那些面臨自己寫接口文檔的情況下無從下手的尷尬的局面半火。
接口文檔書寫
1. 前置描述
●產(chǎn)品文檔，簡單說明背景季俩，接口用來干嘛的
●技術(shù)文檔钮糖，說一說各方的具體實現(xiàn)，復(fù)雜的可以說下具體的設(shè)計思路酌住，n個方案對比店归，貼上sql，ddl酪我，dml設(shè)計消痛，具體代碼等具體能看的東西
2. 方法概覽
●方法路徑，命名統(tǒng)一
●方法名稱都哭，命名統(tǒng)一
●方法類型 get/post…
3. 參數(shù)定義
●參數(shù)命名統(tǒng)一秩伞，下劃線，駝峰…
●類型定義明確欺矫，整形纱新，長整型，浮點穆趴，對象脸爱，指針
●是否需要枚舉 required Enuma a
●是否必填 optional int a //非必填
●必要備注，說明這個字段是干啥的 required int a //不能叫a
●是否需要默認(rèn)值 required int a =0
●如果是比較難懂的字段未妹，貼上相關(guān)說明鏈接 required int a //字段說明http:heheda.com
●如果是部分有特殊意義的string或者數(shù)組簿废，舉例子說明含義，比如 yyyy-mm-dd類型的string
●需要提供idl文件的或者webservice教寂，注意格式化
●http請求可以給到示范的請求返回
●如果是接口變更捏鱼，用特殊標(biāo)記表示，比如字體加紅
簡單版本
核心：如果你的案例可以直接依靠復(fù)制拿來使用酪耕，那這個文檔就是好文檔
既然要簡單，那就抓住核心：怎么簡單怎么來轨淌，怎么省時間怎么來
如果不知道怎么寫迂烁，就把案例寫的越詳細(xì)越好。
開發(fā)時間是非常寶貴的递鹉，而接口對接通常都是一些工期緊張的情況下去快速編寫盟步，而且面對一些碎片化的時間工作者，一份簡單直觀的文檔可能更受歡迎躏结。
另外却盘，接口文檔最終形式最好是pdf，以前遇到過接口文檔寫到word里面的，在不同的版本下可能會出現(xiàn)樣式等各種問題
最佳方式：word -> pdf
簡單版本的目錄格式
●接口說明
●請求示例
●請求參數(shù)說明
●響應(yīng)示例
●響應(yīng)參數(shù)說明
案例模板1：
接口說明：
接口功能：
本接口用于獲取用戶的token信息黄橘。
接口請求地址：
https: xxx/xxx/xxxx
請求頭 :
請求方式: POST
參數(shù)類型 ：JSON
請求示例：
絕大多數(shù)為json兆览，格式自定
[
? ? {"id":"20201219",
? ? "name":"21.59"，
? ? "age":"ftp_1002"
? ? ...
? ? },
? ? {"id":"20201219",
? ? "name":"21.59"塞关，
? ? "age":"ftp_1002"
? ? ...
? ? },
]
請求參數(shù)說明
響應(yīng)示例
成功響應(yīng)編碼：
{
? ? "code: "200",
? ? "message": "請求成功",
? ? "data": 返回數(shù)據(jù)抬探，格式自定
}
失敗響應(yīng)編碼：
{
? ? "code: "200",
? ? "message": "請求成功",
? ? "data": 返回數(shù)據(jù)，格式自定
}
響應(yīng)參數(shù)說明
接口返回碼 接口返回描述
案例模板2：
下面這種模板是單個接口的適合很實用帆赢，同時針對一些比較簡單的接口這樣處理還算比較直觀
核心是一個表包含所有信息小压，這對于一些接口量非常非常大的時候或者接口參數(shù)相似的時候比較有效果，這樣可以使得內(nèi)容比較緊湊椰于，不會看了下一頁忘記上一頁的煩惱怠益，當(dāng)然缺點也很明顯，會存在文字堆積的情況瘾婿。
markdown的表格在存放Json的數(shù)據(jù)時候不是很直觀，建議使用 word
案例模板3：
下面這種可能不是很直觀憋他，但是參考很多文檔發(fā)現(xiàn)好像類似的還不少，也可以參考一下竹挡。
請求地址：http://www.baidu.com
l 屬性列表
l 響應(yīng)屬性列表
l JSON數(shù)據(jù)示例**
[http://xxxxxxxx/xxx/xxx]
請求參數(shù)：
"
? ? {
? ? ? ? “token”,””,? ? ? ? ? ? ? //必填
? ? ? ? “treeCode”,” EXECUTIVE”,? //必填
? ? ? ? “code”,””,? ? ? ? ? ? ? ? //必填
? ? ? ? “entity”,” {
? ? ? ? "code":"2222",? ? ? ? ? ? //必填
? ? ? ? " start_date":"",
? ? ? ? "name":"字段名稱",? ? ? ? //必填
? ? ? ? "end_date ":"",?
? ? ? ? "user_num":"",
? ? ? ? "supplier_name":"",
? ? ? ? “type”,””,? //指定類型?
? ? ? ? "orgUpCode":"11111",? ? ? //必填
? ? ? ? "parentId":"1111111",? ? //必填
? ? ? ? “isDisabled”:” false”? ? //是否禁用
? ? }
"
響應(yīng)：login
JSON - 數(shù)據(jù)示例
{
"success": true,
"data": {
? ? "treeId": "ROOT",
? ? "parentId": 112034,
? ? "name": "3333",
},
"errorCode": null,
"errorName": null,
"errorMessage": null,
"errorException": {
? "name": null,
? "message": null,
? "trace": null
}
}
至此镀娶，一個簡單的接口文檔差不多就是這些內(nèi)容揪罕，下面將會介紹一下復(fù)雜的做法（內(nèi)容較多）
復(fù)雜版本
由于不同的公司有不同的文檔格式要求，這里只給出我看過的幾個文檔羅列下來的一些文檔內(nèi)容好啰，不一定通用轩娶，也不一定是很完美的，但是希望內(nèi)容可以具備一定的參考價值框往。
復(fù)雜版本的內(nèi)容有點多椰弊。請耐心觀看或者收藏再看（=v=）
復(fù)雜版本的目錄格式
+ 封面
? + 接口文檔名稱
? + 接口版本號
? + 版權(quán)說明
+ 文檔信息
? + 標(biāo)題 | 創(chuàng)建時間 | 打印時間 | 文件名 | 存放目錄 | 所有者 | 作用
? + 小題：版權(quán)聲明
+ 版本歷史（重點1）
? + \| 版本號 \| 日期 \| 修改者 \| 描述 \|
? + \| v1.0.0? \| xxx \| xxx \| xxx |
+ 目錄
? + 結(jié)構(gòu)清晰
? + 有條理
? + 能快速定位需要的信息（后文會介紹）
+ 文檔具體內(nèi)容部分
? + 編寫目的
? + 對接準(zhǔn)備事項
? ? + 測試聯(lián)調(diào)
? ? + 上線
? + 使用協(xié)議 + 規(guī)范
? + 報文規(guī)范
? ? + 請求報文規(guī)范
? ? + 響應(yīng)報文規(guī)范
? + 接口描述
? ? + 報文規(guī)范
? ? ? + 請求報文
? ? ? + 響應(yīng)報文
? ? ? + 公共報文頭
? ? ? + 接口碼說明
? ? ? + 業(yè)務(wù)接口
? ? ? + 查詢接口
? ? + 加解密規(guī)范
? ? ? + 原則
? ? ? + 令牌信息
? ? ? + 加密規(guī)范
? ? ? + 解密規(guī)范
? + 業(yè)務(wù)接口
? ? + 具體接口1：
? ? ? + 說明
? ? ? + 規(guī)范碼（查表）
? ? ? + 使用方式
? ? ? + 請求字段
? ? ? + 響應(yīng)字段
? ? ? + 案例
? ? + 具體接口2....
? ? ........
? + 附錄
? ? + 參考資料1
? ? + 參考資料2
? + 其他.....
案例：
封面：
封面還是比較重要的秉版，畢竟是打開文檔的第一眼內(nèi)容，下面用阿里的文檔作為參考清焕，可以看到封面一般是如下內(nèi)容：
●公司名稱
●文檔名稱
●版本號
文檔信息：
文檔信息主要記錄這份文件的產(chǎn)生日期以及具體的創(chuàng)建打印日期等祭犯。
版權(quán)聲明：（現(xiàn)在這個時代版權(quán)是極其重要的）
xxxx所有沃粗，不得三方借閱铐刘、出讓、出版
版本歷史：
版本歷史是很重要的檩禾，每次改動都需要有詳細(xì)的記錄疤祭，這樣才能保證文檔的干凈和有效，同時可以方便review的時候戏售，對于文檔的修訂者進(jìn)行文檔審查
版本號 日期 概述 修訂者
目錄：
好的文檔一定有好的目錄草穆，只要按照一定的規(guī)范和格式寫出來的文檔，一般看上去都是十分舒服的锋喜。還是用阿里的開發(fā)手冊做參考
文檔具體內(nèi)容部分
這一部分發(fā)揮的自由空間就比較大了豌鸡，不同的業(yè)務(wù)不同的公司不同的需求不同的人都能寫出萬千種格式的文檔涯冠，所以這里也是給一個樣例做參考使用。是否有實用價值因人而異蛇更。
為了不讓整個目錄樹太長械荷，這里沒有做標(biāo)題說明=-=
編寫目的：
需要解決什么問題，為什么要這份文檔吨瞎，這份文檔有什么參考價值颤诀？
對接準(zhǔn)備事項：
接口方可以提供什么內(nèi)容，接口方需要對接方的那些內(nèi)容遗淳，以及提供的其他信息心傀，比如需要對接方提供 系統(tǒng)應(yīng)用id，系統(tǒng)唯一標(biāo)識养叛。向?qū)臃教峁┟荑€等等
1. 測試聯(lián)調(diào)：分配測試的密鑰宰翅，測試環(huán)境的賬戶和密碼以及其他信息
2. 上線：上線之后需要做什么事情，如：替換生產(chǎn)url淆攻，替換生產(chǎn)環(huán)境賬戶密碼嘿架，替換密鑰為生產(chǎn)密鑰等等
使用協(xié)議 + 規(guī)范：
可以是本次對接使用的算法耸彪，通信協(xié)議，可以是術(shù)語說明或者和業(yè)務(wù)相關(guān)的其他說明丑瞧，以及對接的要求都可以蜀肘，發(fā)揮空間很大，自由設(shè)計西乖。
報文規(guī)范：
報文規(guī)范是接口對接的核心部分坛增，因為對接大部分的時間基本都是花在接口參數(shù)調(diào)試和請求調(diào)試等。所以報文規(guī)范算是非常重要的內(nèi)容届案。具體內(nèi)容可以參考簡單版本的接口描述罢艾，也可以使用目錄格式進(jìn)行對應(yīng)的描述
加解密規(guī)范：
也是比較重要的部分，也是比較花時間的地方童漩，需要大量調(diào)試來打通接口的地方矫膨，存在以下的幾個要點
●原則：接口存在一些簡單的原則，比如非對稱加密危尿，數(shù)字簽名施禾，時間戳判斷有效性，具體按照接口的原則自由設(shè)置
●令牌信息：描述令牌是如何生成的邮绿，是比較重要的部分攀例，一般由對接雙方溝通完成，最好多以案例和代碼輔助解釋
●加密規(guī)范：描述接口數(shù)據(jù)的加密過程挖胃，比較重要的內(nèi)容信息梆惯，最好多以案例和代碼輔助解釋
●解密規(guī)范：就是解釋接口要如何解密垛吗，比如需要拿到服務(wù)端給過來的配對公鑰才能解密，再比如使用簽名+參數(shù)進(jìn)行對照加密驗證簽名是否正確等怯屉。
加解密規(guī)范參考：
一般的加密方式锨络，一般情況下做到下面這種形式基本可以屏蔽大部分的攻擊：
按照map的key進(jìn)行字典排序，同時加入timetamp值校驗核對時間
把參數(shù)按照一些特殊形式拼接為key=value&key=value的形式礼患，末尾帶入時間戳或者其他的一些信息，比如應(yīng)用Id等核實身份的內(nèi)容
把這一串按照AES加密咏瑟，然后按照BASE64編碼痪署，生成一個編碼串
把BASE64編碼進(jìn)行MD5加密兄旬，加密完成之后领铐，得到固定長度的MD5字符串
按照md5串+上面的string在進(jìn)行一次md5加密，生成簽名瓢姻，那么這個簽名基本上就唯一的
業(yè)務(wù)接口
這里基本可以照抄簡單接口模板音诈，因為接口描述每個人的描述不同，下面給出一些基本上涉及的點褥傍，另外喇聊，到了這一步就盡量用案例輔助，因為案例可以幫助接口閱讀者更快速的上手和理解朋贬，注意這一部分的內(nèi)容：實用性大于理論性
具體接口：
1.說明
2.規(guī)范碼（查表）
3.使用方式
4.請求字段
5.響應(yīng)字段
6.案例
附錄：
可能這部分和說明書一樣基本沒人看窜骄，所以不做過多的解釋，個人到目前為止看過的接口文檔基本沒有遇到附錄寫的很詳細(xì)的御滩，這里可以隨意施展党远。
?本文到此結(jié)束！好看的皮囊千篇一律氛驮、有趣的靈魂萬里挑一济似，創(chuàng)作不易盏缤，離不開寶子們的支持唉铜，喜歡的朋友點點贊和關(guān)注律杠！感謝支持！
