使用apidoc文檔神器，快速生成api文檔

boredream 發布于2019-08-23 16:55 / 612人閱讀

摘要：寫完接口，就需要編寫文檔了，如果一個個手寫的話就很麻煩，就得使用只需要通過寫注釋，就可以快速生成文檔了。組將用于生成的輸出中的主導航。輸出文檔到文件夾，沒有回自動創建。執行訪問就可以看到生成好的文檔了。

寫完api接口，就需要編寫api文檔了，如果一個個手寫的話就很麻煩，就得使用apidoc只需要通過寫注釋，就可以快速生成文檔了。

安裝

第一步先安裝全局模塊apidoc。

npm install apidoc -g

修改接口的注釋

找到novel-api項目routes下面的index.js文件，注釋修改成如下

/**
 * @api {get} /index 請求首頁數據
 * @apiVersion 1.0.0
 * @apiName 獲取首頁數據
 * @apiGroup index
 *
 *
 * @apiSuccess {Number} flag 是否獲取到數據 1成功 0失敗
 * @apiSuccess {Array} books 返回書籍內容
 * @apiSuccess {String} msg  返回信息
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *    {
 *      "flag": 1,
 *      "books": [
 *          {
 *             "_id": "5816b415b06d1d32157790b1",
 *            "title": "圣墟",
 *            "author": "辰東",
 *            "shortIntro": "在破敗中崛起，在寂滅中復蘇。滄海成塵，雷電枯竭，那一縷幽霧又一次臨近大地，世間的枷鎖被打開了，一個全新的世界就此揭開神秘的一角……",
 *            "cover": "http://statics.zhuishushenqi.com/agent/http%3A%2F%2Fimg.1391.com%2Fapi%2Fv1%2Fbookcenter%2Fcover%2F1%2F1228859%2F1228859_fac7917a960547eb953edf0b740cef3a.jpg%2F",
 *            "site": "zhuishuvip",
 *            "majorCate": "玄幻",
 *            "minorCate": "東方玄幻",
 *            "allowMonthly": false,
 *            "banned": 0,
 *            "latelyFollower": 283375,
 *            "retentionRatio": "73.42"
 *          }
 *      ],
 *      "msg": "OK"
 *    }
 *
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     { "flag": 0, "msg": "rankingId有問題" }
 */

@api {method} path [title]
@api 如果沒有@api apidoc會忽略這段注釋
method 請求的方法
path 路徑
title 標題

@apiVersion version
設置文檔塊的版本。
version 版本號

@apiName name
定義方法文檔塊的名稱。名稱將用于生成的輸出中的子導航。
name 方法的名稱

@apiGroup name
定義方法文檔塊屬于哪個組。組將用于生成的輸出中的主導航。
name 組的名稱。也用作導航標題。

@apiSuccess [(group)] [{type}] field [description]
成功返回參數。
(group) 可選所有參數將按這個名稱分組。沒有組，默認Success 200設置。
{type} 可選返回類型
field 返回標識符
description 描述

@apiParamExample [{type}] [title]

               example

參數請求示例。
{type} 可選響應格式
title 示例的簡稱
example 詳細的例子

@apiErrorExample [{type}] [title]

             example

錯誤返回消息的示例，輸出為預格式化代碼。
{type} 可選響應格式
title 示例的簡稱
example 詳細的例子

配置npm run doc

打開package.json文件增加doc命令配置

"doc": "apidoc -i routes/ -o public/"

routes/ 要輸出API文檔的文件夾。
public/ 輸出文檔到public文件夾，沒有回自動創建。
執行 npm run doc
訪問 http://localhost:3000/ 就可以看到生成好的API文檔了。

線上生成的文檔地址

https://api.langpz.com/

我的博客和github，喜歡就去點點星吧，謝謝。

https://github.com/lanpangzhi

http://blog.langpz.com

參考

https://github.com/apidoc/apidoc

GPU云服務器云服務器生成API文檔文檔生成 python生成文檔 python文檔生成

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/103524.html

開源的api文檔管理系統

摘要：國外的話國內的國內開源的非常好用的一款文檔管理系統，安裝也非常方便，只需將源代碼放到項目目錄下自動安裝運行即可，不要要注意版本必須大于界面簡潔功能強大的阿里的接口管理工具，開源免費，接口自動化，數據自動生成，自動化測試，企業級管理。在項目中，需要協同開發，所以會寫許多API文檔給其他同事，以前都是寫一個簡單的TXT文本或Word文檔，口口相傳，這種方式比較老土了，所以，需要有個api...

zsirfs 2019-06-27 14:58 評論0 收藏0
利用apidoc維護api接口文檔

摘要：什么是是一個輕量級的在線接口文檔生成系統，支持多種主流語言，包括和等。使用者按照要求書寫相關注釋，就可以生成可讀性好界面美觀的在線接口文檔。雙擊文件夾下的，就能看到文檔了。什么是apidoc apidoc是一個輕量級的在線REST接口文檔生成系統，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者按照要求書寫相關注釋，就可以生成可讀性好、界面美觀的在線接...

hiyayiji 2019-06-28 13:50 評論0 收藏0
利用apidoc維護api接口文檔

摘要：什么是是一個輕量級的在線接口文檔生成系統，支持多種主流語言，包括和等。使用者按照要求書寫相關注釋，就可以生成可讀性好界面美觀的在線接口文檔。雙擊文件夾下的，就能看到文檔了。什么是apidoc apidoc是一個輕量級的在線REST接口文檔生成系統，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者按照要求書寫相關注釋，就可以生成可讀性好、界面美觀的在線接...

biaoxiaoduan 2019-08-21 16:41 評論0 收藏0
利用apidoc維護api接口文檔

摘要：什么是是一個輕量級的在線接口文檔生成系統，支持多種主流語言，包括和等。使用者按照要求書寫相關注釋，就可以生成可讀性好界面美觀的在線接口文檔。雙擊文件夾下的，就能看到文檔了。什么是apidoc apidoc是一個輕量級的在線REST接口文檔生成系統，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者按照要求書寫相關注釋，就可以生成可讀性好、界面美觀的在線接...

shaonbean 2019-07-30 14:42 評論0 收藏0