Github开源项目之APIDOC
2016-01-20 10:22
357 查看
介绍
生成Restful web API文档,支持大部分的语言,java 、javascript、 php、 python、 c # 、ruby注意:它是根据你源码中的API注释来生成相应的文档的。
github: https://github.com/apidoc/apidoc/
github examples:http://apidocjs.com/#examples
a complex example:http://apidocjs.com/#example-full
使用
通过一个小例子来说明如何使用。1、首先安装Node.js(自行百度)
因为apiDoc是一个node module,所以首先必须安装node.js
2、安装apiDoc
npm install -g apidoc
3、这里选用一个javascript例子来说明,新建一个目录my_project,然后在该目录下新建example.js
1)首先,我们对getUser()方法做一个最基本的标注文档
var currentUser = {
name: 'Mary'
};
/**
*@api{get}/user Request User information
*@apiName GetUser
*@apiGroup User
*{
*name:'Paul',
*age:27
*}
*/
function getUser() {
return {
code: 200,
data: currentUser
};
}
function setName(name) {
if (name.length === 0) {
return {
code: 404,
message: 'NameEmptyError'
};
}
currentUser.name = name;
return {
code: 204
};
}
@api 客户端调用该方法的路径
@apiName 唯一标识的名称,可以任意命名,推荐命名方式,方法类型和方法名的组合,例如{get}和/user=>GetUser
@apiGroup 该方法属于的组名。组名将用于导航
注意:以上三个参数是必须的。
好,我们现在转到my_project目录下,在cmd中运行apidoc
apidoc
这里,注意下,如果使用默认的apidoc,它会在当前目录和子目录下搜索所有的文件(可识别的文件包括.js、.java等等),你可以设置文件过滤,可以通过apidoc -h查询更多信息。
打开doc/index.html文件
2)现在我们添加API的响应注释
/**
*@api{get}/user Request User information
*@apiName GetUser
*@apiGroup User
*@apiSuccess{String}name The users name
*/
function getUser() {
return {
code: 200,
data: currentUser
};
}
重新运行apidoc,覆盖doc目录。
3)增加版本号和示例信息
/**
*@api{get}/user Request User information
*@apiName GetUser
*@apiGroup User
*@apiVersion 0.1.0
*@apiSuccess{String}name The users name
*@apiSuccessExample Example data on success
*{
* name:'Paul'
*}
*/
function getUser() {
return {
code: 200,
data: currentUser
};
}
4)如果要发布新的版本,可能有很多接口信息需要变动。我们新建一个"_apidoc.js"文件,将之前的注释信息放入文件中。
_apidoc.js
/**
*@api{get}/user Request User information
*@apiName GetUser
*@apiGroup User
*@apiVersion 0.1.0
*@apiSuccess{String}name The users name
*@apiSuccessExample Example data on success
*{
* name:'Paul'
*}
*/"_apidoc.js表示注释信息的历史文件"
现在我们在新文件中改变example.js文件
/**
*@api{get}/user Request User information
*@apiName GetUser
*@apiGroup User
*@apiVersion 0.2.0
*@apiSuccess{String}name The users name
*@apiSuccess{Number}age Calculated age from Birthday
*@apiSuccessExample Example data on success
*{
* name:'Paul',
* age:27
*}
*/
function getUser() {
return {
code: 200,
data: currentUser
};
}
再一次运行apidoc文件
不仅可以看0.2.0的版本,还可以与0.1.0的版本对比。
5)给setName()方法增加相关的注释信息
/**
*@api{put}/user Change User
*@apiName PutUser
*@apiGroup User
*@apiVersion 0.1.0
*@apiParam{String}name New name of the user
*@apiError NameEmptyError The name was empty.Minimum of<code>1</code>character is required.
*/
function setName(name) {
if (name.length === 0) {
return {
code: 404,
message: 'NameEmptyError'
};
}
currentUser.name = name;
return {
code: 204
};
}
运行apidoc,打开index页面如下所示。
文章原文:https://speakerdeck.com/rottmann/api-documentation
相关文章推荐
- Ruby微信开发的几个开源项目介绍
- 利用AJAX开源项目 在网页里播放视频实现方法
- 使用PHP把HTML生成PDF文件的几个开源项目介绍
- 机器学习---学习首页 3ff0
- nice-repo 搜集优秀的开源项目
- 关于开源项目《Scavenger》
- 如何做一个真正牛X 的开源项目
- 我用过的几个开源GIS软件
- 10款GitHub上最火爆的国产开源项目
- web service, wcf, web api
- 参与到开原项目中去
- 10个关于人工智能和机器学习的有趣开源项目
- Firefly-RK3288系统界面预览
- Android非常有用的开源库介绍整理
- 需求加入开源项目,为社区做贡献
- gnome-logs开发记录1--起源--Gnome开发记录
- gnome-logs开发记录4--noob重构代码就是这个feel
- gnome-logs开发记录3--修复bug726228+杂记
- 成也JAVA 败也JAVA