前言
目前，越来越多的项目进行前后端分离，那么就有需要比较规范的来管理API文档。而apiDoc这个API文档管理器，可以根据你项目代码的注释来进行自动生成API文档。同时支持C#、Java、JavaScript、PHP、Python等语言。
下面为具体的详细步骤。
事前准备
- node安装，前往Node.js进行下载安装，这里一直点击下一步就可以了，很简单。（我安装的是V6.9.1）版本。
安装apiDoc
输入下面的命令进行安装
sudo npm install apidoc -g
安装完成，就是这么简单。
使用apiDoc创建文档
-
创建项目目录
mkdir doc && cd doc
这条命了创建了一个叫doc的文件夹，创建成功后进入doc文件夹，下面如无特别说明，所有命令均在doc文件夹下执行。
-
创建源文件目录与输出文件目录
mkdir src && mkdir output
在doc文件夹下创建了src目录和output目录。其中src文件夹用来写API文档，output文件夹用来存放编译后的API文档。
- 创建描述文件
在doc文件夹下新建一个名为apidoc.json的文件，此文件的作用是用来描述API文档的相关信息。作用类似于composer.json或者前端的package.json文件，并且这个描述信息可以直接写到package.json文件中，具体的使用方法可以上官网进行查询。
下面是apidoc.json文件的内容。
|
1 2 3 4 5 6 7 8 |
{ "name": "Coolcode", "version": "0.1.0", "description": "趣编程API文档", "title": "趣编程API文档", "url" : "http://apidoc.coolcode.tech" } |
- 接着在
src文件夹下新建test.js文件，也可以是PHP、java等文件。文件内容如下
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
/** * @api {get} /test 测试路由 * @apiName TestRoute * @apiGroup Test * * * @apiSuccess {Array} Body message. * * @apiSuccessExample Success-Response: * [ * "api 项目运行成功" * ] * * @apiError 404 404 Not Found. * * @apiErrorExample Error-Response: * { * "error": "404 Not Found" * } */ |
- 接着在终端输入下面的命令来生成API文档。
apidoc -i src/ -o output/
上面的命令表示将所有src文件夹内的代码全部转换成API文档并且输出到output文件夹内。如果代码编写正确的话，此时在终端内会出现info: Done字样。代表我们已经成功创建了API文档。
接着在浏览器中打开output文件夹下的index.html文件就会看到已经排版好的API文档了。
至此，一个基本的API文档已经生成。接下来讲解一下apidoc的一些进阶用法。
apiDoc进阶用法
- 继承
在src文件夹下新建classes.php文件。代码如下。
|
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 33 34 35 36 37 38 39 40 41 42 |
/** * @apiDefine ClassNotFoundError * * @apiError ClassNotFound The id of the Class was not found. * * @apiErrorExample Error-Response: * { * "error": "UserNotFound" * } */ /** * @api {get} /classes/:id 班级详情 * @apiName GetClass * @apiGroup Class * * @apiParam {Number} id 班级ID. * * @apiSuccess {String} name 班级名称 ...... * * @apiSuccessExample Success-Response: ...... * } * * @apiUse ClassNotFoundError */ /** * @api {get} /classes/:id/current_mentees 班级当前学员 * @apiName GetClassCurrentMentees * @apiGroup Class * * @apiParam {Collection} body 班级当前学员. * * @apiSuccessExample Success-Response: ...... * * @apiUse ClassNotFoundError */ |
上面的代码只写出了主要部分，省略部分用省略号代替，具体代码前往gitlab上进行查看。
在上面的代码中，我们在最开始使用@apiDefine来定义了一个公用错误返回示例。在下面的两个api中可以使用@apiUse来调用这个示例。这样我们就不用为不同API的相同错误来写两遍了。
最终的效果可以到（趣编程API文档）来进行查看。
还有许多其他apiDoc的功能可以到官网去查找使用，也许你们写出来的文档会比我写的更加好呢。