REST开放接口生成文档工具之apidoc
2017-02-08 09:08
369 查看
一、安装node.js环境
感谢阿里云,下载的链接http://npm.taobao.org/mirrors/node/latest-v6.x/
二、安装apidoc
npm install apidoc -g
三、背景准备
1.以Java为例,新建一个java项目,假设名为test。
2.新建一个文本文件,命名apidoc.json,放置在test项目src根目录下。
3.新建一个Java文件,假设名为Test.java。
四、编写apidoc.json
这是在自动生成文档时的基础设置信息。
{ "name": "apidoc-example", "version": "0.3.0", "description": "apiDoc example project", "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1", "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" }, "order": [ "GetUser", "PostUser" ], "template": { "withCompare": true, "withGenerator": true } }
五、一个GET请求的示例
打开Test.java文件,在文件内写入以下注释。
/** * @api {get} /pokka/:id pokka * @apiName 获取指定Pokka * @apiVersion 0.1.0 * @apiGroup Pokka * @apiDescription 这是描述信息,可以有多行。 * @apiExample {curl} 接口示例: * curl -i http://localhost/pokka/4711 * @apiHeader {String} access-key 请求头必须携带字段access-key * @apiHeaderExample {json} 头部示例: * { * "access-key": "按照约定加密方式产生的token==" * } * * @apiSuccess (200) {String} firstname 姓氏 * @apiSuccess (200) {String} lastname 名称 * * @apiSuccessExample {json} 成功的响应: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * */
这些注释相对简单,能直观的看出来定义了
1. 接口格式(必选)
2. 接口名称
3. 接口版本
4. 接口所属组(必选)
5. 接口描述信息
6. 接口格式示例
7. 接口头定义
8. 接口头示例
9. 接口成功响应定义
六、接口成功响应示例
实际情况中,还会遇到携带参数的POST请求、错误的响应等等更多API描述需求。
更多的学习api地址:http://apidocjs.com/#params
七、最终的执行
命令格式为apidoc -i 项目实际目录 -o 希望输出到的目录
例如apidoc -i D:\workspace\test -o D:\api-output
八、得到的结果
如果没有报错的话,进入D:\api-output,双击index.html就可以看到漂亮的接口文档了。
例如此例得到的描述页面。
![](https://images2015.cnblogs.com/blog/725532/201702/725532-20170208090752354-1765057300.png)
相关文章推荐
- apidoc接口文档自动生成工具
- Web API文档生成工具apidoc
- Web API文档生成工具apidoc
- Web API文档生成工具apidoc 的使用步骤
- app后端开发二:API接口文档自动生成工具
- 用apidoc 生成在线接口文档
- 文档生成工具 APIDOC 笔记
- php markdown 接口文档生成工具 SummerDoc
- Web API文档生成工具apidoc
- 使用apidoc生成接口文档
- apidoc ----api文档生成工具的使用
- nodejs下的apidoc 帮助接口文档生成
- Spring Rest Docs WebTestClient自动生成接口文档Gradle版
- RESTful API文档生成工具Wisdom RESTClient
- spring boot rest接口自动生成文档(包含swagger)
- 使用apidoc自动生成rest风格api接口文档
- apidoc接口文档的快速生成
- Web API文档生成工具apidoc
- DotNet 项目开发文档的自动生成和相关工具的使用
- C# CHM帮助文档生成工具-Sandcastle