api文檔生成器apidoc的安裝和使用

在開發接口的過程中，需要向外發布相應的接口文檔。開始的時候使用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的用法相類似。