寫在前面：這是我最近整理的接口規范文檔，無規矩不成方圓，為了app開發人員與后臺接口開發人員更好的配合，我特意整理了這么一篇文檔供大家參考學習，如有意見請在評論區留言謝謝。因部分內容涉及公司代碼，我對本文檔略有刪減。

接口規范說起來大，其實也就那么幾個部分，接口規范、接口管理工具、接口文檔編寫、開發文檔編寫。以下將詳細介紹，下面進入正文：

接口規范文檔 具體內容如下： 一：協議規范 二：域名規范 三：版本控制規范 四：API路徑規范 五：API命名規范 六：請求參數規范 七：列表請求特殊規范 八：返回數據規范 九：接口文檔規范 十：接口管理工具使用教程

參與編寫	更新日期	版本	備注
AbyssKitty	2018/04/06	V1.1.0	無

V1.1.0更新日志： 1.?新增協議規范、域名規范、版本控制規范、列表特殊規范。 2.?更新接口管理工具使用教程。 3.?美化排版。 正文： 一：協議規范 為進一步確保數據交互安全。正式地址（生產地址）必須遵循HTTPS協議。 二：域名規范 每個項目要有且僅有一個自己唯一的域名+端口。在項目配置文件中要添加靜態變量專門進行存儲。 如果一個域名滿足不了要求，那么就需要再添加一個。 格式規范如下： （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開頭，并以“/”結尾。 三：API路徑規范 作為接口路徑，為了和其他路徑完美區分，必須在路徑中添加api目錄 格式規范如下： （java）public static final String URL_API = “api/”; （PHP）php目錄是加index.php/api/ 必須以字母開頭，并以“/”結尾。 四：版本控制規范 項目正式上線后，正式版本要確定接口版本、并備份接口代碼。 為方便管理，需要在接口路徑中加入版本號信息。 格式規范如下： （java）public static final String URL_VERSION =”v1/”; 必須以字母開頭，并以“/”結尾。 更新版本后可以使用v2 v3等、依次遞加。 五：API命名規范 根據二：域名規范、三：API路徑規范、四：版本控制規范。項目中必須在配置文件中增加BaseUrl靜態常量。值=三個相加。 格式規范如下： （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/”] 重要的事情說三遍。 根據業務需求，可以在v1版本文件夾里創建，一個或者多個接口文件。 一個的規范： https://127.0.0.1:8080/api/v1/getBanner 這就是一個獲取banner的接口。 多個的規范是根據業務需求來區分： https://127.0.0.1:8080/api/v1/home/getBanner https://127.0.0.1:8080/api/v1/user/userLogin 新建user文件，里面存放用戶級別的操作：如登陸、注冊、修改密碼等等。 新建sms文件，里面存放對短信的接口操作：如發送驗證碼、驗證手機號等等。 所以，接口方法文件必須要有自己的規范，命名必須統一使用駝峰命名法或者下劃線拼接命名法。舉個栗子：（upperCamelCase）（upper_camel_case）。所有接口命名方式，必須遵循如下規范。 （1）新增方法：如新增一個地址、新增一個聯系人。 命名規范： 必須以“add”為前綴。例如addAddress 事例地址：https://127.0.0.1:8080/api/v1/addAddress （2）刪除方法：如刪除一個地址。 命名規范： 必須以“delete”為前綴。例如deleteAddress 事例地址：https://127.0.0.1:8080/api/v1/deleteAddress （3）修改方法：如修改一個地址。 命名規范： 必須以“updata”為前綴。例如updataAddress 事例地址：https://127.0.0.1:8080/api/v1/updataAddress （4）獲取方法：如獲取一個地址。 命名規范： 必須以“get”為前綴。例如getAddress 事例地址：https://127.0.0.1:8080/api/v1/getAddress （5）獲取列表方法：如獲取一個地址列表。 命名規范： 必須以“get”為前綴、“List”為后綴。例如getAddressList 事例地址：https://127.0.0.1:8080/api/v1/getAddressList ? 其他規范： 發送驗證碼使用‘send’為前綴、保存一個數據以‘save’為前綴、上傳圖片以‘uploadImage’為名稱等等。 具體地址就等于（BASEURL+“address/getAddressList”） 目的：一目了然、降低維護成本。 六：請求參數規范 請求方式：公共數據使用get方式請求，私有數據使用post方式請求。盡量全部是用post。 請求頭：請求頭根據項目需求添加配置參數。如：accept=‘application/json ’等。請求頭根據項目需求可以要求傳入用戶token、app名稱版本、唯一驗簽碼等加密數據。 ????請求參數： 根據數據庫字段進行命名、保持一致最省事。 七：列表請求特殊規范 列表請求，請求參數規范，必須傳參：頁數和每頁個數的字段。并可包含查詢等信息。 1.?列表接口必傳字段（分頁、使用小寫字母）。 page ：頁數，從1開始。例如：{ “page”: 1 ?} subnumber : 每頁數量。 2.?列表接口選傳字段。 只要是列表接口、一般情況下都會存在檢索條件，例如淘寶商品檢索。檢索條件為選填。 后臺需進行非空非null判斷，選傳字段為空為null默認查詢全部。有值則需要接收，并進行sql查詢。 規范事例： 普通列表接口：https://127.0.0.1:8080/api/v1/getBannerList （不傳page、后臺默認返回全部數據） （banner接口不需要使用檢索條件） 需檢索列表接口：https://127.0.0.1:8080/api/v1/getOrderList （不傳page、后臺默認返回全部數據） （Order訂單接口需要檢索條件，不傳就不檢索，只進行分頁查詢） （如果有 time price等檢索條件，不傳就不檢索，傳了就進行條件查詢，并返回相應數據） 八：返回數據規范 注：列表數據返回，沒有特殊情況的條件下，必須最新數據在上面，依次排序。 返回事例： { "list":[], "object":{}, //"object":"" "status":"SUCCESS", "message":"我是提示消息", ?... "page":1, "subnumber":10, } 必選-命名規范：駝峰命名法。 必選-新增鍵值規則：名字對應固定的格式（list就是數組[]）。 舉個栗子：比如一個"list":[]滿足不了需求，那么可以新增一個"map":[]。 比如一個"object":{"name":"小明"}滿足不了需求，那么可以新增一個"details":{"name":"小紅"}。名字對應固定的格式，數組就是數組、實體類就是實體類、字段就是字段。不能data在這個接口返回的是實體類、另一個接口又返回數組了。需要特別注意。 必選-list：list列表（數組）為空時顯示[]。 必選-object：實體數據，json鍵值對。 必選-status：狀態信息=SUCCESS、ERROR等靜態變量。 必選-message：提示消息。（加載成功、） 可選-page：頁數（分頁查新時使用、顯示第幾頁從一開始）。 可選-subnumber：每頁的格式（分頁查詢時使用、顯示當前頁的個數）。 九：接口文檔規范 接口文檔需要包含以下部分： 文檔名稱。 版本號。 編寫人。 編寫、修改日期。 baseUrl地址。 更新日志。 接口詳情。（詳情規范如下） 接口詳情編輯規范： 一個完整的接口需要由以下幾部分組成 1.請求地址 例如：https://127.0.0.1:8080/xxx/xxx/xxx 2.請求方式 例如：POST、GET等 3.請求參數 例如：傳 id：“1”，name：“小明” 4.返回參數 例如：{ json... } 【參考上面的接口規范】 5.返回事例 例如：{ json... } 十：接口管理工具使用教程 接口管理工具有很多，例如RAP、eolinker等等。 接口管理工具基本的作用都是用來管理接口的。這里簡單介紹eolinker的使用方法。 使用方法步驟： 創建接口管理項目。 邀請開發者同事加入。 編寫接口（接口地址、請求參數及備注、請求方式、返回參數及備注、返回事例、在線測試接口）。 開發者使用接口。 過程中靈活配合，接口可以靈活更新。 完成項目后可以導出接口文檔。 附件：XXX接口管理工具使用教程點擊進入eolinker使用教程 RAP的特色： RAP是一個GUI的WEB接口管理工具。在RAP中，您可定義接口的URL、請求&響應細節格式等等。通過分析這些數據，RAP提供MOCK服務、測試服務等自動化工具。RAP同時提供大量企業級功能，幫助企業和團隊高效的工作。 在前后端分離的開發模式下，我們通常需要定義一份接口文檔來規范接口的具體信息。如一個請求的地址、有幾個參數、參數名稱及類型含義等等。RAP 首先方便團隊錄入、查看和管理這些接口文檔，并通過分析結構化的文檔數據，重復利用并生成自測數據、提供自測控制臺等等... 大幅度提升開發效率。 強大的GUI工具 給力的用戶體驗，你將會愛上使用RAP來管理您的API文檔。 完善的MOCK服務 文檔定義好的瞬間，所有接口已經準備就緒。有了MockJS，無論您的業務模型有多復雜，它都能很好的滿足。 龐大的用戶群 RAP在阿里巴巴有200多個大型項目在使用，也有許多著名的公司、開源人士在使用。RAP跟隨這些業務的成行而成長，專注細節，把握質量，經得住考驗。 免費 + 專業的技術支持 RAP是免費的，而且你的技術咨詢都將在24小時內得到答復。大多數情況，在1小時內會得到答復。 RAP是一個可視化接口管理工具 通過分析接口結構，動態生成模擬數據，校驗真實接口正確性， 圍繞接口定義，通過一系列自動化工具提升我們的協作效率。 ? 完本。
如果有什么建議或者意見，請在郵箱或者評論區留言，謝謝。 我的郵箱：zhangtaoandroid@163.com

總結

以上是生活随笔為你收集整理的接口规范文档总结、接口管理工具推荐、如何写出完美的接口的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。