在開發接口的過程中,需要向外發佈相應的接口文檔。開始的時候使用word來寫文檔,時間長了發現有幾個問題。
1. 編寫不方便。每次新增藉口的時候都要複製上一個接口,然後再進行修改,一些相同的部分無法複用,接口多了文檔會變的很長,還經常需要調整格式。
2. 發佈不方便。文檔更新時,需要發給需要的小夥伴。即使用git來進行管理,雖然拉取比較方便,但由於文件格式的問題,也不方便比較兩次提交的差異。
由於有這些問題,決定尋找一種更優雅有效的方式來編寫文檔。經過比較,發現了apidoc,可以比較好的解決上面提到的問題。apidoc採用了一種類似寫代碼註釋的方式來寫文檔,支持編寫多種語言的文檔。最後生成的文檔以網頁的形式發佈,方便快捷,便於閱讀。下面就來簡單介紹一下怎麼使用apidoc來寫文檔。
安裝
1. 由於apidoc依賴node.js的包管理工具npm進行安裝,所以安裝apidoc之前要先安裝node.js(npm會在安裝node時順帶進行安裝)。具體的安裝教程可以參考這裏。
2. 安裝完了npm之後,就可以安裝apidoc了。在命令行輸入
npm install apidoc -g
就可以進行安裝了。安裝完成輸入
apidoc -h
出現相關的提示幫助信息,說明安裝成功了。
使用
1. 在需要生成文檔的地方新建一個apidoc.json文件,配置如下
{
"name": "appleFarm",//文檔項目名
"title": "appleFarmAPI",//html標題
"description":"appleFarmAPI接口文檔",//文檔描述
"url" : "https://farm.05948166.com",//公共接口地址
"version": "0.1.0"//文檔版本
}
2. 在新建apidoc.json的地方打開命令行輸入apidoc即可在本目錄下生成doc目錄直接訪問即可
語法
舉個栗子
/**
* @api {get} /articles/:id 根據單個id獲取文章信息
* @apiName 根據id獲取文章信息
* @apiGroup Articles
*
* @apiParam (params) {String} id 文章id
*
* @apiSuccess {Array} article 返回相應id的文章信息
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "tile": "文章標題2",
* "date": 1483941498230,
* "author": "classlfz",
* "content": "文章的詳細內容"
* }
*
* @apiError (Error 4xx) 404 對應id的文章信息不存在
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 對應id的文章信息不存在
* {
* "error": err
* }
*/
詳細介紹
@api
@api一般是必須編寫的(除非你是用了@apiDefine),不然apidoc編譯器會忽略這段註釋。
/**
* @api {method} path [title]
*/
參數 | 描述 |
---|---|
method | 請求的方法名稱:如GET、POST等等 |
path | 請求路徑(只需要拼寫apidoc.json中配置地址的後面部分即可) |
title(可選) | 一個簡短的標題(用於導航跟文檔標題) |
@apiGroup
定於api歸屬的組名,生成的文檔會把該api註釋歸類到該值對應的api組上。
/**
* @apiGroup name
*/
參數 | 描述 |
---|---|
name | 歸屬組名稱 |
@apiName
@apiName用於定義API文檔的一個實例,並用作實例名稱 。
/**
* @apiName name
*/
參數 | 描述 |
---|---|
name | 實例名稱 |
@apiParam
@apiParam用於編寫API的參數以及參數的解釋。
/**
* @apiParam [(group)] [{type}] [field=defaultValue] [description]
*/
參數 | 描述 |
---|---|
(group) 可選 | 參數歸屬組名,不填寫組名,則默認設爲Paramter |
{type} 可選 | 參數數據類型,如{String}、{Number}、{Array}等等 |
{type{size}} 可選 | 變量的大小信息 {String{..5}}參數類型爲一個字符不超過5的字符串;{String{2..5}}參數爲一個字符在2到5之間的字符串; |
{type=allowedValues} 可選 | 參數允許值 {string=”small”,”huge”}參數只能接受small或者huge的字符串 |
field 可選 | 參數名稱 |
=defaultValue | 參數默認值 |
description(可選) | 描述 |
@apiParamExample
@apiParamExample參數舉例
/**
* @apiParamExample [{type}] [title]
* example
*/
參數 | 描述 |
---|---|
{type} 可選 | 請求數據結構 |
title 可選 | 例子的一個簡短的標題 |
example | 例子的詳細信息,可多個例子並存 |
@apiSuccess
請求成功後的返回字段參數
/**
* @apiSuccessExample [{type}] [title] example
*/
參數 | 描述 |
---|---|
(group) 可選 | 參數歸屬組名,不填寫組名,則默認設爲Success 200 |
{type} 可選 | 返回的數據類型,如{String}、{Number}等等 |
field | 返回的標示符(返回成功的狀態碼) |
description 可選 | 描述 |
@apiSuccessExample
請求成功後返回的字段參數例子
/**
* @apiSuccessExample [{type}] [title] example
*/
參數 | 描述 |
---|---|
{type} 可選 | 請求數據結構 |
title 可選 | 例子的一個簡短的標題 |
example | 例子的詳細信息,可多個例子並存 |
@apiError & @apiErrorExample
這個的用法跟@apiSuccess、@apiSuccessExample的用法相類似。