股票场内基金交易,没时间盯盘?
前言
目前,越来越多的项目进行前后端分离,那么就有需要比较规范的来管理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的功能可以到官网去查找使用,也许你们写出来的文档会比我写的更加好呢。
想获得去掉 5 元限制的证券账户吗?

如果您想去掉最低交易佣金 5 元限制,使用微信扫描左边小程序二维码,访问微信小程序「优财助手」,点击底部菜单「福利」,阅读文章「通过优财开证券账户无最低交易佣金 5 元限制」,按照文章步骤操作即可获得免 5 元证券账户,股票基金交易手续费率万 2.5。
请注意,一定要按照文章描述严格操作,如错误开户是无法获得免 5 元证券账户的。