接口規范說起來大，其實也就那么幾個部分，接口規范、接口管理工具、接口文檔編寫、開發文檔編寫。以下將詳細介紹，下面進入正文：
接口規范文檔
具體內容如下：
一：協議規范
二：域名規范
三：版本控制規范
四：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版本文件夾里創建，一個或者多個接口文件。
一個的規范：
這就是一個獲取banner的接口。
多個的規范是根據業務需求來區分：
新建user文件，里面存放用戶級別的操作：如登陸、注冊、修改密碼等等。
新建sms文件，里面存放對短信的接口操作：如發送驗證碼、驗證手機號等等。
所以，接口方法文件必須要有自己的規范，命名必須統一使用駝峰命名法或者下划線拼接命名法。舉個栗子：（upperCamelCase）（upper_camel_case）。所有接口命名方式，必須遵循如下規范。
（1）新增方法：如新增一個地址、新增一個聯系人。
命名規范：
必須以“add”為前綴。例如addAddress
（2）刪除方法：如刪除一個地址。
命名規范：
必須以“delete”為前綴。例如deleteAddress
（3）修改方法：如修改一個地址。
命名規范：
必須以“updata”為前綴。例如updataAddress
（4）獲取方法：如獲取一個地址。
命名規范：
必須以“get”為前綴。例如getAddress
（5）獲取列表方法：如獲取一個地址列表。
命名規范：
必須以“get”為前綴、“List”為后綴。例如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查詢。
規范事例：
（不傳page、后台默認返回全部數據）
（banner接口不需要使用檢索條件）
（不傳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的使用方法。
使用方法步驟：
創建接口管理項目。
邀請開發者同事加入。
編寫接口（接口地址、請求參數及備注、請求方式、返回參數及備注、返回事例、在線測試接口）。
開發者使用接口。
過程中靈活配合，接口可以靈活更新。
完成項目后可以導出接口文檔。
1. 查詢指定項目屬性
接口功能
獲取制定項目的分類信息
URL
http://www.api.com/index.php
支持格式
JSON
HTTP請求方式
GET
請求參數
參數 必選 類型 說明
name ture string 請求的項目名
type true int 請求項目的類型。1：類型一；2：類型二 。
返回字段
返回字段 字段類型 說明
status int 返回結果狀態。0：正常；1：錯誤。
company string 所屬公司名
category string 所屬類型
接口示例
地址：http://www.api.com/index.php?name=”可口可樂”&type=1
{
"statue": 0,
"company": "可口可樂",
"category": "飲料",
}
1
2
3
4
5
markdown源碼如下：
目錄
1\. 查詢指定項目屬性接口
---
**1\. 查詢指定項目屬性**
###### 接口功能
> 獲取制定項目的分類信息
###### URL
> [http://www.api.com/index.php](www.api.com/index.php)
###### 支持格式
> JSON
###### HTTP請求方式
> GET
###### 請求參數
> |參數|必選|類型|說明|
|:----- |:-------|:-----|----- |
|name |ture |string|請求的項目名 |
|type |true |int |請求項目的類型。1：類型一；2：類型二 。|
###### 返回字段
> |返回字段|字段類型|說明 |
|:----- |:------|:----------------------------- |
|status |int |返回結果狀態。0：正常；1：錯誤。 |
|company |string | 所屬公司名 |
|category |string |所屬類型 |
###### 接口示例
> 地址：[http://www.api.com/index.php?name="可口可樂"&type=1](http://www.api.com/index.php?name="可口可樂"&type=1)
``` javascript
{
"statue": 0,
"company": "可口可樂",
"category": "飲料",
}
---------------------
