java api doc的可读性_利用apidoc维护api接口文档

什么是apidoc

apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档。

快速开始

安装依赖

安装nodejs https://nodejs.org/官网下载.msi文件；

测试是否安装成功 npm -v

npm的安装。由于新版的NodeJS已经集成了npm，所以之前npm也一并安装好了。同样可以使用cmd命令行输入"npm -v"来测试是否成功安装。如下图，出现版本提示便OK了。

安装apidoc

利用npm进行安装

npm install apidoc -g

安装速度和网速有关，最多1到2分钟，

apidoc -v 可以查看版本信息

安装好后在

C:\Users\admin\AppData\Roaming\npm\node_modules\apidoc

能够看到如下文件

apidoc配置

打开example文件夹apidoc.json为配置文件,修改参数为自己的项目信息。

{

"name": "apidoc-example",

"version": "0.3.0",

"description": "apidoc example project",

"title": "Custom apiDoc browser title",

"url" : "https://api.github.com/v1",

"sampleUrl": "https://api.github.com/v1",

"header": {

"title": "My own header title",

"filename": "header.md"

},

"footer": {

"title": "My own footer title",

"filename": "footer.md"

},

"template": {

"withCompare": true,

"withGenerator": true

}

}

将 apidoc.json 拷贝到需要生成文档的目录下

然后按照文档说明做代码注释

/**

* @api {get} /sguoshan_api/Logon 获取用户信息

* @apiVersion 1.0.0

* @apiName Logon

* @apiGroup User

* @apiPermission 所有已注册用户

* @apiPrivate

* @apiDescription 与0.9.0相比安全性提高

*

* @apiParam {String} username 用户名称/邮箱/会员号

* @apiParam {Number} password 用户密码

* @apiExample 使用示例:

* http://api.guoshanchina.com/sguoshan_api/Logon?username=911117&password=123456

*

* @apiSuccess {Number} id The Users-ID.

* @apiSuccess {Date} registered Registration Date.

* @apiSuccess {Date} name Fullname of the User.

* @apiSuccess {String[]} nicknames List of Users nicknames (Array of Strings).

* @apiSuccess {Object} profile Profile data (example for an Object)

* @apiSuccess {Number} profile.age Users age.

* @apiSuccess {String} profile.image Avatar-Image.

* @apiSuccess {Object[]} options List of Users options (Array of Objects).

* @apiSuccess {String} options.name Option Name.

* @apiSuccess {String} options.value Option Value.

*

* @apiSuccessExample 成功 return ():

{

"msg": "获取成功",

"status":"200",

"data":{

"id":"123",

"name":"shmily"

}

}

* @apiError NoAccessRight 只用登陆成功才能访问.

* @apiError UserNotFound 用户 id 错误.

* @apiErrorExample 失败 return ():

* HTTP/1.1 401 Not Authenticated

* {

* "msg": "没有权限","status":"401"

* }

*/

function getUser() { return; }

在命令行中

切换到项目apidoc.json的上一级(api目录)

d:

cd www/shop/Web

apidoc -i api/ -o apidoc/

运行后在api的同级目录能够看到生成了apidoc的文件夹。双击文件夹下的index.html，就能看到文档了。