apiDoc生成接口文檔,不費吹灰之力

效果

背景

以前作前端的時候,後端同窗仗着本身是老同志,不給我接口文檔

苦逼如我,須要拿着筆坐在他的旁邊,聽他口述

寫下須要的api接口url和參數等等

如今本身作後端了,那不能這樣子胡做非爲了

本身吃的苦,怎能給其餘同窗吃呢?

這時候,apiDoc你值得擁有,穩穩的輸出一篇優質的接口文檔

安裝apidoc

官網上是全局安裝,我是喜歡安裝到項目中,這樣能夠在另外一個環境下,npm install就能夠下載有全部依賴包

npm install apidoc --save-dev/-D

寫註釋

註冊接口的註釋

/**
 * @api {post} /v1/auth/register User Register
 * @apiName UserRegister
 * @apiGroup userAuthentication
 *
 * @apiParam {String} username  New user's username.
 * @apiParam {String} password  New user's password.
 *
 * @apiSuccess {String} username  The username of the register user.
 * @apiSuccess {string} message  The registering success info.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "username": "username",
 *       "message": "User registered successful"
 *     }
 *
 * @apiError REGISTER_FAILURE The register failure.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 500 Internal Server Error
 *    {
 *      "err": "REGISTER_FAILURE",
 *      "message": "User register failure!"
 *    }
 */

刪除接口的註釋

/**
 * @api {delete} /v1/auth/user/ User delete
 * @apiName UserDelete
 * @apiGroup userAuthentication
 *
 * @apiParam {String} username  User's username.
 * @apiParam {String} executor  Executor of this operation.
 *
 * @apiSuccess {String} username  The username of the deleted user.
 * @apiSuccess {string} message  The message if deleting successful.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *   {
 *     "username": "username",
 *     "message": "Delete User Successful"
 *   }
 *
 * @apiError NOT_LOGIN The register failure.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 401 Unauthorized
 *    {
 *      "err": "NOT_LOGIN",
 *      "message": "User has not logon in!"
 *    }
 */

寫入命令

將apidoc -i routers/寫入package.json的命令中

routers文件夾下都是路由文件

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "lint": "eslint .",
    "apidoc": "apidoc -i routers/",
    "dev": "node --harmony index.js"
  },

出現了{"message":"Done.","level":"info"},即成功了

執行命令

執行npm run apidoc便可拿到接口文檔

這樣,在項目中就會出現doc文件夾

生成文檔

這樣,doc文件夾中包含該頁面的全部材料

打開index.html

熱乎乎的接口文檔誕生了

結構解讀

一個靜態的文檔很漂亮的生成了，可是實際控制這個方法的是api_data.js和api_project.js。可是實際上的數據顯示是由api_data.json和api_project.json這兩個json文件。

因此在支持將其餘json格式轉換成api_data.json和api_project.json，把apidoc生成的這兩個文件進行替換，而後替換js文件，直接生產靜態文檔。

命令行界面

查看全部命令

apidoc -h

選項	做用
-f --file-filters	用於選擇應分析的文件的regex篩選器（可使用多個-f）。（默認值：[]）
-e, --exclude-filters	用於選擇不該解析的文件/目錄的regex篩選器（可使用many-e）。（默認值：[]）
-i, --input	輸入/源目錄名。（默認值：[]）
-o, --output	輸出目錄。（默認：「./doc/」）
-t, --template	對輸出文件使用模板。（默認值：「/usr/local/lib/node_modules/apidoc/template/」）
-c, --config	包含配置文件（apidoc.json）的目錄路徑。（默認值：「./」）
-p, --private	Include private APIs in output.
-v, --verbose	詳細調試輸出。
--debug	顯示調試消息。
--color	關閉日誌顏色。
--parse	只解析文件並返回數據，不建立文件。
--parse-filters	可選的用戶定義篩選器。格式名=文件名（默認值：[]）
--parse-languages	可選的用戶定義語言。格式名=文件名（默認值：[]
--parse-parsers	可選的用戶定義的分析器。格式名=文件名（默認值：[]）
--parse-workers	可選的用戶定義的工做人員。格式名=文件名（默認值：[]）
--silent	關閉全部輸出。
--simulate	執行但不寫入任何文件。
--markdown [markdown]	關閉默認標記分析器或將文件設置爲自定義分析器。（默認值：真）
--line-ending	關閉自動檢測行尾。容許值：lf，cr，crlf。
--encoding	設置源代碼的編碼。[UTF8]格式。（默認值：「utf8」）
-h, --help	輸出使用信息

所用的的apiDoc的參數(翻譯)

@api

@api {method} path [title]

必需的！
若是沒有該指示器，apidoc解析器將忽略文檔塊。
惟一的例外是@apidefine定義的文檔塊，它們不須要@api。

Usage: @api {get} /user/:id Users unique ID.

Name	Description
method	Request method name: DELETE, GET, POST, PUT, ...
path	Request Path.
title optional	A short title. (used for navigation and article header)

/**
 * @api {get} /user/:id
 */

@apiName

@apiName name

應始終使用。
定義方法文檔塊的名稱。名稱將用於生成的輸出中的子導航。結構定義不須要@apinname。
用法：@apinname getuser

Name	Description
name	方法的惟一名稱。能夠定義相同的名稱和不一樣的@apiversion。格式：method+path（例如get+user），只有一個建議，您能夠根據須要命名。也能夠用做導航標題。

/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

@apiGroup

@apiGroup name

應始終使用。
定義方法文檔塊所屬的組。組將用於生成的輸出中的主導航。結構定義不須要@apigroup。
用法：@apigroup user

Name	Description
name	組名稱。也使用導航標題。

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述傳遞給API方法的參數。

用法：@apiparam（mygroup）number id users unique id。

Name	Description
(group)optional	全部參數都將按此名稱分組。若是沒有組，則設置默認參數。您可使用@apidefine設置標題和說明。
{type}optional	參數類型,如{Boolean}, {Number}, {String}, {Object}, {String[]}
{type{size}}optional	變量大小的信息{string{..5}} 最大值爲5的字符串.{string{2..5}} 最小2最大爲5的字符串.{number{100-999}} 在100到999的i數字.
{type=allowedValues}optional	有關變量容許值的信息。{string="small"} 包含small的字符串,{string="small","huge"}包含small/huge的字符串,{number=1,2,3,99}一個容許值是1,2,3,和99的數字,{string {..5}="small","huge"}最多5個字符的字符串，只包含單詞「small」或「mage」。
field	變量名稱.
[field]	帶括號的fieldname將變量定義爲可選變量。
=defaultValueoptional	參數默認值。
descriptionoptional	字段的說明。

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

成功返回參數。
用法：@apiSuccess {String} firstname Firstname of the User。

Name	Description
(group)optional	全部參數都將按此名稱分組。

若是沒有組，則設置默認成功200。
您可使用@apidefine設置標題和說明。
{type}optional|返回類型,如{Boolean}, {Number}, {String}, {Object}, {String[]}
field|返回標識符（返回成功代碼）。
description optional|字段的說明。

/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

Example with (group), more group-examples at @apiSuccessTitle:

/**
 * @api {get} /user/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

Example with Object:

/**
 * @api {get} /user/:id
 * @apiSuccess {Boolean} active        Specify if the account is active.
 * @apiSuccess {Object}  profile       User profile information.
 * @apiSuccess {Number}  profile.age   Users age.
 * @apiSuccess {String}  profile.image Avatar-Image.
 */

Example with Array:

/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles       List of user profiles.
 * @apiSuccess {Number}   profiles.age   Users age.
 * @apiSuccess {String}   profiles.image Avatar-Image.
 */

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

成功返回消息的示例，輸出爲預先格式化的代碼。
用途：` @apiSuccessExample {json} Success-Response:

{ "content": "This is an example content" }`

Name	Description
typeoptional	響應格式
titleoptional	示例的簡短標題
example	詳細示例，支持多行

/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

@apiError

@apiError [(group)] [{type}] field [description]

成功返回參數。
用法：@apiError UserNotFound。

Name	Description
(group)optional	全部參數都將按此名稱分組。若是沒有組，則設置默認錯誤4xx。您可使用@apidefine設置標題和說明。
{type}optional	返回類型,如{Boolean}, {Number}, {String}, {Object}, {String[]}
field	返回標識符（返回失敗代碼）。
description optional	字段的說明。

/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example

失敗返回消息的示例，輸出爲預先格式化的代碼。
用途：` @apiErrorExample {json} Error-Response:

This is an example. `

Name	Description
typeoptional	響應格式
titleoptional	示例的簡短標題
example	詳細示例，支持多行

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

參考文獻

apidoc官網

接口文檔神器之apidoc

apidoc快速生成在線文檔，apidoc生成靜態文件的生成規則，原理分析，實踐

---

1. 歡迎你們進羣,參與討論
2. 一塊兒進步,是咱們的準則,咱們是前端的一道美麗風景線
3. 請加個人vx：qiufeihong0203,拉你進羣

---

1. 歡迎關注feihong的掘金帳號。
2. 原文地址。

---

版權聲明

轉載時請註明做者 qiufeihong 以及本文地址：http://www.qiufeihong.top/technical-summary/apiDoc/