apidoc 生成Restful web Api文档
2016-08-19 00:00
295 查看
在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下!
该工具是Nodejs的模块,请务必在使用前安装好nodejs环境!
2.安装后在cmd终端执行npm install apidoc –g如果执行失败跳到步骤3
3.安装npm首先先安装Homebrew在终端ruby -e "$(curl –fsSL
https://raw.githubusercontent.com/Homebrew/install/master/install)"
4.执行成功终端输入brew install node等待一段时间
5.执行成功终端输入npm –v确认是否npm安装成功
6.安装npm成功后执行执行npm install apidoc –g 安装apidoc即可。
2.在对应接口上加上注释:
示例:
3.执行终端命令apidoc -i example/ -o doc/执行成功就则会在该目录下生成doc文件。
示例:
apidoc -i e:\example -o e:\doc
这样就会在e:\doc目录下生成项目的doc文档,点开index.html就会看到如下效果
详细文档参考http://caixw.oschina.io/apidoc/
该工具是Nodejs的模块,请务必在使用前安装好nodejs环境!
一.安装Apidoc
1.安装nmp环境,Windows环境可直接通过http://nodejs.org/下载安装包安装2.安装后在cmd终端执行npm install apidoc –g如果执行失败跳到步骤3
3.安装npm首先先安装Homebrew在终端ruby -e "$(curl –fsSL
https://raw.githubusercontent.com/Homebrew/install/master/install)"
4.执行成功终端输入brew install node等待一段时间
5.执行成功终端输入npm –v确认是否npm安装成功
6.安装npm成功后执行执行npm install apidoc –g 安装apidoc即可。
二.apidoc使用
1.在项目根目录中创建apidoc.json文件{ "name": "Apidoc Example", "version": "1.0.0", "description": "Apidoc Example descrption", "title": "Custom apiDoc browser title", "url" : "http://localhost:8080/v1", "sampleUrl": "http://localhost:8080/v1", "forceLanguage":"zh-cn", "template": { "withCompare": true, "withGenerator": true } }
2.在对应接口上加上注释:
示例:
/** * * @api {post} /m/login.do 登录 * @apiName 登录 * @apiGroup login * @apiVersion 1.0.0 * @apiDescription 接口详细描述 * * @apiParam {String} username 用户名 * @apiParam {String} password 密码 * * @apiSuccess {String} status 结果码 * @apiSuccess {String} msg 消息说明 * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * status:0, * msg:'success', * data:{} * } * * @apiError All 对应<code>id</code>的用户没找到 * @apiErrorExample {json} Error-Response: * HTTP/1.1 200 * { * code:-1, * msg:'user not found', * } */
3.执行终端命令apidoc -i example/ -o doc/执行成功就则会在该目录下生成doc文件。
// 典型用法 apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$" -i 表示输入,后面是文件夹路径 -o 表示输出,后面是文件夹路径 默认会带上-c,在当前路径下寻找配置文件(apidoc.json),如果找不到则会在package.json中寻找 "apidoc": { } -f 为文件过滤,后面是正则表达式,示例为只选着js文件 与-f类似,还有一个 -e 的选项,表示要排除的文件/文件夹,也是使用正则表达式
示例:
apidoc -i e:\example -o e:\doc
这样就会在e:\doc目录下生成项目的doc文档,点开index.html就会看到如下效果
三.apidoc代码注释
apidoc支持如下关键字
@api {method} path [title] 只有使用@api标注的注释块才会在解析之后生成文档,title会被解析为导航菜单(@apiGroup)下的小菜单 method可以有空格,如{POST GET} @apiGroup name 分组名称,被解析为导航栏菜单 @apiName name 接口名称,在同一个@apiGroup下,名称相同的@api通过@apiVersion区分,否者后面@api会覆盖前面定义的@api @apiDescription text 接口描述,支持html语法 @apiVersion verison 接口版本,major.minor.patch的形式 @apiIgnore [hint] apidoc会忽略使用@apiIgnore标注的接口,hint为描述 @apiSampleRequest url 接口测试地址以供测试,发送请求时,@api method必须为POST/GET等其中一种 @apiDefine name [title] [description] 定义一个注释块(不包含@api),配合@apiUse使用可以引入注释块 在@apiDefine内部不可以使用@apiUse @apiUse name 引入一个@apiDefine的注释块 @apiParam [(group)] [{type}] [field=defaultValue] [description] @apiHeader [(group)] [{type}] [field=defaultValue] [description] @apiError [(group)] [{type}] field [description] @apiSuccess [(group)] [{type}] field [description] 用法基本类似,分别描述请求参数、头部,响应错误和成功 group表示参数的分组,type表示类型(不能有空格),入参可以定义默认值(不能有空格) @apiParamExample [{type}] [title] example @apiHeaderExample [{type}] [title] example @apiErrorExample [{type}] [title] example @apiSuccessExample [{type}] [title] example 用法完全一致,但是type表示的是example的语言类型 example书写成什么样就会解析成什么样,所以最好是书写的时候注意格式化,(许多编辑器都有列模式,可以使用列模式快速对代码添加*号) @apiPermission name name必须独一无二,描述@api的访问权限,如admin/anyone
详细文档参考http://caixw.oschina.io/apidoc/
相关文章推荐
- Android Manifest 用法
- 什么是 GraphQL?
- Spark RDD API详解(一) Map和Reduce
- Spring Boot 开发微服务
- lwn拾遗:[sn3218 led drivers]-api解释-1
- 页面元素查找之Selectors API
- 一个小型js框架myJSFrame附API使用帮助
- 详细分析交换机、路由器、集线器的区别和联系
- PowerShell打开或关闭光驱
- 批处理的api WMIC学习体会有感第1/2页
- 批处理 API实现文件下载的代码第1/2页
- Lua教程(十七):C API简介
- 强制删除工具 xdelbox xdelbox1.5正式版下载
- 揪出交换机端口背后“凶手”导致网速太慢
- 电脑重启后突然检测不到硬盘的原因分析与解决办法
- C#中设计、使用Fluent API
- Google官方支持的NodeJS访问API,提供后台登录授权
- PQ分区出错! 巧用Ghost急速补救的绝妙办法
- 深入C++中API的问题详解
- 使用WindowsAPI实现播放PCM音频的方法