如何利用apidoc编写rest风格的文档

java

一、ApiDoc是什么

事实上我们大多时候说的apidoc实际上是apidoc.js，是使用nodejs命令行模块来生成文档的

首先你需要安装nodejs，mac上直接使用brew安装很简单,执行下面命令即可

1
brew install node

二、安装ApiDoc

然后安装apidoc吧

1
npm install apidoc -g

三、生成API

首先，我们创建一个task-api目录来初始化目录

1
2
3
mkdir task-api
cd task-api
npm init

执行npm init之后就会让你填写很多信息，name，version，main，repository，keywords，author，懂的就填写一下，不懂的直接回车,系统会帮你创建一个package.json文件。

为了建立我们的api代码，我们创建一个index.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
var express = require('express');  
var app = express();
// 为了public文件夹服务
app.use(express.static('public'));
app.get('/tasks', function(req, res) {  
    // business logic for list all tasks...
});
app.get('/tasks/:id', function(req, res) {  
    // business logic for find a task...
});
app.post('/tasks', function(req, res) {  
    // business logic for create a task...
});
app.put('/tasks/:id', function(req, res) {  
    // business logic for update a task...
});
app.delete('/tasks/:id', function(req, res) {  
    // business logic for delete a task...
});
app.listen(3000, function() {  
    console.log('Task api up and running...');
});

这行代码app.use(express.static('public'))将启用public文件夹的静态服务，这个目录将成所有的文档文件。

四、API路由

OK，准备完毕，我们可以开始写我们的api了，我们需要使用apidoc提供的一些简单参数

然后你需要创建一个apidoc.json文件，在根目录，包括这些参数，也可以直接把apidoc这些属性直接放到上面package.json目录下。

1
2
3
4
5
6
7
8
{
    "name": "Task API documentation",//文档名称
    "version": "1.0.0",//文档版本号
    "description": "API task list manager",//文档描述
    "template": {
        "forceLanguage": "en"//语言
    }
}

设置template下面的forceLanguage可以屏蔽浏览器的语言检测，强制使用英语

有这些参数可以设置：

  • name：项目名称
  • version：项目版本
  • description：项目介绍
  • title：浏览器显示的标题内容
  • url：endpoints的前缀，例如https://api.github.com/v1
  • sampleUrl：如果设置了，则在api文档中出现一个测试用的from表单
  • header
  • title：导航文字包含header.md文件
  • filename：markdown-file 文件名
  • footer
  • title：导航文字包含header.md文件
  • filename：markdown-file 文件名
  • order：用于配置输出 api-names/group-names 排序，在列表中的将按照列表中的顺序排序，不在列表中的名称将自动显示。

OK，下面我们开始文档的编写。

编辑index.js，首先我们在app.get('/tasks')方法上面编辑，我们可以加入下面这些参数

  • @api: http方法 、地址和方法名称;
  • @apiGroup: 属于哪一个路由组;
  • @apiSuccess: 描述成功返回
  • @apiSuccessExample: 展示返回值
  • @apiErrorExample: 展示失败值

直接看下代码吧。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/**
 * @api {get} /tasks 展示所有的任务
 * @apiGroup Tasks   //属于task组
 * @apiSuccess {Object[]} tasks Task's list
 * @apiSuccess {Number} tasks.id Task id
 * @apiSuccess {String} tasks.title Task title
 * @apiSuccess {Boolean} tasks.done Task is done?
 * @apiSuccess {Date} tasks.updated_at Update's date
 * @apiSuccess {Date} tasks.created_at Register's date
 * @apiSuccessExample {json} Success
 *    HTTP/1.1 200 OK
 *    [{
 *      "id": 1,
 *      "title": "Study",
 *      "done": false
 *      "updated_at": "2016-02-10T15:46:51.778Z",
 *      "created_at": "2016-02-10T15:46:51.778Z"
 *    }]
 * @apiErrorExample {json} List error
 *    HTTP/1.1 500 Internal Server Error
 */
app.get('/tasks', function(req, res) {  
    // business logic for listing all tasks...
});

下一个路由路径、我们加入了一个新的参数

  • @apiParam: 描述路径下的参数
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
/**
 * @api {get} /tasks/:id Find a task
 * @apiGroup Tasks
 * @apiParam {id} id Task id
 * @apiSuccess {Number} id Task id
 * @apiSuccess {String} title Task title
 * @apiSuccess {Boolean} done Task is done?
 * @apiSuccess {Date} updated_at Update's date
 * @apiSuccess {Date} created_at Register's date
 * @apiSuccessExample {json} Success
 *    HTTP/1.1 200 OK
 *    {
 *      "id": 1,
 *      "title": "Study",
 *      "done": false
 *      "updated_at": "2016-02-10T15:46:51.778Z",
 *      "created_at": "2016-02-10T15:46:51.778Z"
 *    }
 * @apiErrorExample {json} Task not found
 *    HTTP/1.1 404 Not Found
 * @apiErrorExample {json} Find error
 *    HTTP/1.1 500 Internal Server Error
 */
app.get('/tasks/:id', function(req, res) {  
    // business logic for finding a task...
});

辣么如何使用post方法呢？

就会用到@apiParam 和 @apiParamExample ，为了解释body里面返回的参数，done=false表示默认值。看下面

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/**
 * @api {post} /tasks Register a new task
 * @apiGroup Tasks
 * @apiParam {String} title Task title
 * @apiParamExample {json} Input
 *    {
 *      "title": "Study"
 *    }
 * @apiSuccess {Number} id Task id
 * @apiSuccess {String} title Task title
 * @apiSuccess {Boolean} done=false Task is done?
 * @apiSuccess {Date} updated_at Update date
 * @apiSuccess {Date} created_at Register date
 * @apiSuccessExample {json} Success
 *    HTTP/1.1 200 OK
 *    {
 *      "id": 1,
 *      "title": "Study",
 *      "done": false,
 *      "updated_at": "2016-02-10T15:46:51.778Z",
 *      "created_at": "2016-02-10T15:46:51.778Z"
 *    }
 * @apiErrorExample {json} Register error
 *    HTTP/1.1 500 Internal Server Error
 */
app.post('/tasks', function(req, res) {  
    // business logic for creating a task...
});

下面展示put和delete方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/**
 * @api {put} /tasks/:id Update a task
 * @apiGroup Tasks
 * @apiParam {id} id Task id
 * @apiParam {String} title Task title
 * @apiParam {Boolean} done Task is done?
 * @apiParamExample {json} Input
 *    {
 *      "title": "Work",
 *      "done": true
 *    }
 * @apiSuccessExample {json} Success
 *    HTTP/1.1 204 No Content
 * @apiErrorExample {json} Update error
 *    HTTP/1.1 500 Internal Server Error
 */
app.put('/tasks/:id', function(req, res) {  
    // business logic for update a task
});
/**
 * @api {delete} /tasks/:id Remove a task
 * @apiGroup Tasks
 * @apiParam {id} id Task id
 * @apiSuccessExample {json} Success
 *    HTTP/1.1 204 No Content
 * @apiErrorExample {json} Delete error
 *    HTTP/1.1 500 Internal Server Error
 */
app.delete('/tasks/:id', function(req, res) {  
    // business logic for deleting a task
});

ok ,可以生产文档了，使用下面的命令(i 是input代表输入文件夹，o是output代表输出文件夹)

1
2
apidoc  -i public / -o  apidoc  
node index.js  //(你没有这个js就不要执行这个咯，这个是我上面js用的，监听3000端口的)

你就可以访问localhost:3000/apidoc，赶紧自己动手试试吧

图片例子

OK，我们已经完成了所有的任务

Share