[toc] # 什么是API文檔? > API文檔類型是`看云特有的一種文檔類型`，可以`快速定義和生成`產品或項目的API文檔 # API文檔長什么樣? 官方demo [百度空氣質量Api](http://www.hmoore.net/shuai/api_demo/67274) [成語查詢Api](http://www.hmoore.net/shuai/api_demo/67276) # 讓你的文檔支持api語法 修改文檔配置 ```json { "plugins": [ "api", "highlight" ], "pluginsConfig": { "api": { "url": "http://www.kancloud.com", "headers": { "key1":"value1" }, "params":[ { "default": "默認值", "desc": "說明文字", "name": "iid", "required": true, "type": "string" } ], "explore":true } } } ``` 配置講解 >[info] url > api提交的基礎url， > 如這里設置的是http://www.kancloud.com, 你的api定義到URL地址是/user , > 那么此條api實際提交的地址是http://www.kancloud.com/user >[success] headers(可選) > 是一個數組，測試時作為http headers提交到服務器 >[danger] params(可選) > 所有api都有都公共參數，是一個數組，每個數組元素有如下屬性： > >>[danger] default：默認值 >> desc：字段說明 >> name：字段名 >> required：是否必填 >> type：字段類型 >[warning] explore > 是否開啟在線調試功能，有些api可能需要內網環境，無法在線調試，則可關閉此項 # 編寫一個`用戶登錄/注冊二合一`接口 流程圖 ```[flow] st=>start: Start e=>end: End 接收用戶名和密碼=>operation: 接收用戶名和密碼 使用用戶名查詢數據庫=>operation: 使用用戶名查詢數據庫 數據庫中是否有數據=>condition: 數據庫中是否有數據? 走登錄邏輯=>operation: 走登錄邏輯 走注冊邏輯=>operation: 走注冊邏輯 密碼是否正確=>condition: 密碼是否正確? 把用戶名和密碼寫入數據庫=>inputoutput: 把用戶名和密碼寫入數據庫 st->接收用戶名和密碼->使用用戶名查詢數據庫->數據庫中是否有數據 數據庫中是否有數據(yes)->走登錄邏輯->密碼是否正確 數據庫中是否有數據(no)->走注冊邏輯->把用戶名和密碼寫入數據庫->e 密碼是否正確(yes)->e 密碼是否正確(no,down)->接收用戶名和密碼 ``` 接口實例 ~~~[api] post:/justForTest/api/user/userLogin *string:user_name=15612345678#用戶手機號 *string:user_pwd#密碼 <<< success { "ret": 0, # 返回狀態碼 "data": { "user_id": 1 // 用戶id }, } <<< error { "success": 0, // 請求成功! "user_name_wrong": 1, // 密碼不正確! "insert_wrong": 2, // 數據庫寫入用戶信息失敗! "query_wrong": 3, // 獲取用戶信息失敗! } ~~~ 接口代碼 ``` ~~~[api] post:/justForTest/api/user/userLogin *string:user_name=15612345678#用戶手機號 *string:user_pwd#密碼 <<< success { "ret": 0, # 返回狀態碼 "data": { "user_id": 1 // 用戶id }, } <<< error { "success": 0, // 請求成功! "user_name_wrong": 1, // 密碼不正確! "insert_wrong": 2, // 數據庫寫入用戶信息失敗! "query_wrong": 3, // 獲取用戶信息失敗! } ~~~ ``` # 代碼語法分析 ``` ~~~[api] get:/url *id=默認值#說明文字 name#說明文字 <<< success { "errNum": 0, "retMsg": "success", "retData": {} } <<< error 這里填寫錯誤的返回碼 以此類推，每個狀態使用 <<< 分割, 第一行添加狀態名稱 ~~~ ```