接口規(guī)范文檔
具體內(nèi)容如下：
一：協(xié)議規(guī)范
二：域名規(guī)范
三：版本控制規(guī)范
四：API路徑規(guī)范
五：API命名規(guī)范
六：請求參數(shù)規(guī)范
七：列表請求特殊規(guī)范
八：返回數(shù)據(jù)規(guī)范
九：接口文檔規(guī)范
十：接口管理工具使用教程
| 參與編寫 | 更新日期 | 版本 | 備注 |
|---|---|---|---|
| AbyssKitty | 2018/04/06 | V1.1.0 | 無 |
V1.1.0更新日志：
新增協(xié)議規(guī)范谭确、域名規(guī)范娃弓、版本控制規(guī)范扔役、列表特殊規(guī)范。
更新接口管理工具使用教程。
美化排版煌妈。
正文：
一：協(xié)議規(guī)范
為進(jìn)一步確保數(shù)據(jù)交互安全。正式地址（生產(chǎn)地址）必須遵循HTTPS協(xié)議。
二：域名規(guī)范
每個項目要有且僅有一個自己唯一的域名+端口慢味。在項目配置文件中要添加靜態(tài)變量專門進(jìn)行存儲。
如果一個域名滿足不了要求墅冷，那么就需要再添加一個纯路。
格式規(guī)范如下：
（java）public static final String URL_BASE = “https://127.0.0.1:8080/”;
（java）public static final String URL_BASE_SUB = “https://192.168.0.1:8080/”;
必須以https開頭，并以“/”結(jié)尾寞忿。
三：API路徑規(guī)范
作為接口路徑驰唬，為了和其他路徑完美區(qū)分，必須在路徑中添加api目錄
格式規(guī)范如下：
（java）public static final String URL_API = “api/”;
（PHP）php目錄是加index.php/api/
必須以字母開頭绢要，并以“/”結(jié)尾席赂。
四：版本控制規(guī)范
項目正式上線后虱歪，正式版本要確定接口版本、并備份接口代碼搓逾。
為方便管理，需要在接口路徑中加入版本號信息上炎。
格式規(guī)范如下：
（java）public static final String URL_VERSION =”v1/”;
必須以字母開頭恃逻，并以“/”結(jié)尾雏搂。
更新版本后可以使用v2 v3等、依次遞加寇损。
五：API命名規(guī)范
根據(jù)二：域名規(guī)范凸郑、三：API路徑規(guī)范、四：版本控制規(guī)范矛市。項目中必須在配置文件中增加BaseUrl靜態(tài)常量芙沥。值=三個相加。
格式規(guī)范如下：
（java）public static final String BASEURL=URL_BASE+URL_API+URL_VERSION;
具體代碼如下：
BASEURL = [“https://127.0.0.1:8080/api/v1/”]
BASEURL = [“https://127.0.0.1:8080/api/v1/”]
BASEURL = [“https://127.0.0.1:8080/api/v1/”]
重要的事情說三遍浊吏。
根據(jù)業(yè)務(wù)需求而昨，可以在v1版本文件夾里創(chuàng)建，一個或者多個接口文件找田。
一個的規(guī)范：
https://127.0.0.1:8080/api/v1/getBanner
這就是一個獲取banner的接口歌憨。
多個的規(guī)范是根據(jù)業(yè)務(wù)需求來區(qū)分：
https://127.0.0.1:8080/api/v1/home/getBanner
https://127.0.0.1:8080/api/v1/user/userLogin
新建user文件，里面存放用戶級別的操作：如登陸墩衙、注冊务嫡、修改密碼等等。
新建sms文件漆改，里面存放對短信的接口操作：如發(fā)送驗證碼心铃、驗證手機(jī)號等等。
所以挫剑，接口方法文件必須要有自己的規(guī)范去扣，命名必須統(tǒng)一使用駝峰命名法或者下劃線拼接命名法。舉個栗子：（upperCamelCase）（upper_camel_case）樊破。所有接口命名方式愉棱，必須遵循如下規(guī)范。
（1）新增方法：如新增一個地址捶码、新增一個聯(lián)系人羽氮。
命名規(guī)范：
必須以“add”為前綴。例如addAddress
事例地址：https://127.0.0.1:8080/api/v1/addAddress
（2）刪除方法：如刪除一個地址惫恼。
命名規(guī)范：
必須以“delete”為前綴档押。例如deleteAddress
事例地址：https://127.0.0.1:8080/api/v1/deleteAddress
（3）修改方法：如修改一個地址。
命名規(guī)范：
必須以“updata”為前綴祈纯。例如updataAddress
事例地址：https://127.0.0.1:8080/api/v1/updataAddress
（4）獲取方法：如獲取一個地址令宿。
命名規(guī)范：
必須以“get”為前綴。例如getAddress
事例地址：https://127.0.0.1:8080/api/v1/getAddress
（5）獲取列表方法：如獲取一個地址列表腕窥。
命名規(guī)范：
必須以“get”為前綴粒没、“List”為后綴。例如getAddressList
事例地址：https://127.0.0.1:8080/api/v1/getAddressList
其他規(guī)范：
發(fā)送驗證碼使用‘send’為前綴簇爆、保存一個數(shù)據(jù)以‘save’為前綴癞松、上傳圖片以‘uploadImage’為名稱等等爽撒。
具體地址就等于（BASEURL+“address/getAddressList”）
目的：一目了然、降低維護(hù)成本响蓉。
六：請求參數(shù)規(guī)范
請求方式：公共數(shù)據(jù)使用get方式請求硕勿，私有數(shù)據(jù)使用post方式請求。盡量全部是用post枫甲。
請求頭：請求頭根據(jù)項目需求添加配置參數(shù)源武。如：accept=‘a(chǎn)pplication/json
’等。請求頭根據(jù)項目需求可以要求傳入用戶token想幻、app名稱版本粱栖、唯一驗簽碼等加密數(shù)據(jù)。
? 請求參數(shù)：
根據(jù)數(shù)據(jù)庫字段進(jìn)行命名脏毯、保持一致最省事闹究。
七：列表請求特殊規(guī)范
列表請求，請求參數(shù)規(guī)范抄沮，必須傳參：頁數(shù)和每頁個數(shù)的字段跋核。并可包含查詢等信息。
- 列表接口必傳字段（分頁叛买、使用小寫字母）。
**page **：頁數(shù)蹋订，從1開始率挣。例如：{ “page”: 1 }
**subnumber **: 每頁數(shù)量。
- 列表接口選傳字段露戒。
只要是列表接口椒功、一般情況下都會存在檢索條件，例如淘寶商品檢索智什。檢索條件為選填动漾。
后臺需進(jìn)行非空非null判斷，選傳字段為空為null默認(rèn)查詢?nèi)寇АＳ兄祫t需要接收旱眯，并進(jìn)行sql查詢。
規(guī)范事例：
普通列表接口：https://127.0.0.1:8080/api/v1/getBannerList
（不傳page证九、后臺默認(rèn)返回全部數(shù)據(jù)）
（banner接口不需要使用檢索條件）
需檢索列表接口：https://127.0.0.1:8080/api/v1/getOrderList
（不傳page删豺、后臺默認(rèn)返回全部數(shù)據(jù)）
（Order訂單接口需要檢索條件，不傳就不檢索愧怜，只進(jìn)行分頁查詢）
（如果有 time price等檢索條件呀页，不傳就不檢索，傳了就進(jìn)行條件查詢拥坛，并返回相應(yīng)數(shù)據(jù)）
八：返回數(shù)據(jù)規(guī)范
注：列表數(shù)據(jù)返回蓬蝶，沒有特殊情況的條件下尘分，必須最新數(shù)據(jù)在上面，依次排序丸氛。
返回事例：
{
"list":[],
"object":{}, //"object":""
"status":"SUCCESS",
"message":"我是提示消息",
** ...**
"page":1,
"subnumber":10,
}
必選-命名規(guī)范：駝峰命名法培愁。
必選-新增鍵值規(guī)則：名字對應(yīng)固定的格式（list就是數(shù)組[]）。
舉個栗子：比如一個"list":[]滿足不了需求雪位，那么可以新增一個"map":[]竭钝。
比如一個"object":{"name":"小明"}滿足不了需求，那么可以新增一個"details":{"name":"小紅"}雹洗。名字對應(yīng)固定的格式香罐，數(shù)組就是數(shù)組、實體類就是實體類时肿、字段就是字段庇茫。不能data在這個接口返回的是實體類、另一個接口又返回數(shù)組了螃成。需要特別注意旦签。
必選-list：list列表（數(shù)組）為空時顯示[]。
必選-object：實體數(shù)據(jù)寸宏，json鍵值對宁炫。
必選-status：狀態(tài)信息=SUCCESS、ERROR等靜態(tài)變量氮凝。
必選-message：提示消息羔巢。（加載成功、）
可選-page：頁數(shù)（分頁查新時使用罩阵、顯示第幾頁從一開始）竿秆。
可選-subnumber：每頁的格式（分頁查詢時使用、顯示當(dāng)前頁的個數(shù)）稿壁。
九：接口文檔規(guī)范
接口文檔需要包含以下部分：
文檔名稱幽钢。
版本號。
編寫人傅是。
編寫匪燕、修改日期。
baseUrl地址落午。
更新日志谎懦。
接口詳情。（詳情規(guī)范如下）
接口詳情編輯規(guī)范：
一個完整的接口需要由以下幾部分組成
1.請求地址 例如：https://127.0.0.1:8080/xxx/xxx/xxx
2.請求方式 例如：POST溃斋、GET等
3.請求參數(shù) 例如：傳 id：“1”界拦，name：“小明”
4.返回參數(shù) 例如：{ json... } 【參考上面的接口規(guī)范】
5.返回事例 例如：{ json... }
十：接口管理工具使用教程
接口管理工具有很多，例如RAP梗劫、eolinker等等享甸。
接口管理工具基本的作用都是用來管理接口的截碴。這里簡單介紹eolinker的使用方法。
使用方法步驟：
創(chuàng)建接口管理項目蛉威。
邀請開發(fā)者同事加入日丹。
編寫接口（接口地址、請求參數(shù)及備注蚯嫌、請求方式哲虾、返回參數(shù)及備注、返回事例择示、在線測試接口）束凑。
開發(fā)者使用接口。
過程中靈活配合栅盲，接口可以靈活更新汪诉。
完成項目后可以導(dǎo)出接口文檔。
附件：XXX接口管理工具使用教程點(diǎn)擊進(jìn)入eolinker使用教程
RAP的特色：
RAP是一個GUI的WEB接口管理工具谈秫。在RAP中扒寄，您可定義接口的URL、請求&響應(yīng)細(xì)節(jié)格式等等拟烫。通過分析這些數(shù)據(jù)该编，RAP提供MOCK服務(wù)、測試服務(wù)等自動化工具硕淑。RAP同時提供大量企業(yè)級功能上渴，幫助企業(yè)和團(tuán)隊高效的工作。
在前后端分離的開發(fā)模式下喜颁，我們通常需要定義一份接口文檔來規(guī)范接口的具體信息。如一個請求的地址曹阔、有幾個參數(shù)半开、參數(shù)名稱及類型含義等等。RAP 首先方便團(tuán)隊錄入赃份、查看和管理這些接口文檔寂拆，并通過分析結(jié)構(gòu)化的文檔數(shù)據(jù)，重復(fù)利用并生成自測數(shù)據(jù)抓韩、提供自測控制臺等等... 大幅度提升開發(fā)效率纠永。
強(qiáng)大的GUI工具 給力的用戶體驗，你將會愛上使用RAP來管理您的API文檔谒拴。
完善的MOCK服務(wù) 文檔定義好的瞬間尝江，所有接口已經(jīng)準(zhǔn)備就緒。有了MockJS英上，無論您的業(yè)務(wù)模型有多復(fù)雜炭序，它都能很好的滿足啤覆。
龐大的用戶群 RAP在阿里巴巴有200多個大型項目在使用，也有許多著名的公司惭聂、開源人士在使用窗声。RAP跟隨這些業(yè)務(wù)的成行而成長，專注細(xì)節(jié)辜纲，把握質(zhì)量笨觅，經(jīng)得住考驗。
免費(fèi) + 專業(yè)的技術(shù)支持 RAP是免費(fèi)的耕腾，而且你的技術(shù)咨詢都將在24小時內(nèi)得到答復(fù)见剩。大多數(shù)情況，在1小時內(nèi)會得到答復(fù)幽邓。
RAP是一個可視化接口管理工具 通過分析接口結(jié)構(gòu)炮温，動態(tài)生成模擬數(shù)據(jù)，校驗真實接口正確性牵舵， 圍繞接口定義柒啤，通過一系列自動化工具提升我們的協(xié)作效率。
完本畸颅。
