yum install npm -y
npm install apidoc -g
apidoc -v
{
"name": "API名称",
"version": "API主版本号,仅支持3位数字版本号,如:0.0.1",
"description": "API描述信息",
"title": "浏览器标题",
"url": "可选,接口地址,如:http://wuloves.com/xxx",
"sampleUrl": "可选,接口调用示例地址,如增加此项,则页面会增加可发送请求示例的操作项",
"header": {
"title": "可选,头部标题",
"filename": "可选,头部文件路径,只支持.md文件"
},
"footer": {
"title": "可选,底部描述",
"filename": "可选,底部文件路径,只支持.md文件"
},
"template": {
"withCompare": true, //是否允许版本之间进行比较
"withGenerator": true//是否允许生成多个版本
}
}
@api {get} /users/:user_id Request User Information
最主要的参数,”{get}”定义了HTTP请求是GET,API地址是”/users/:user_id”,文档中API的名称是”Request User Information”。
@apiVersion 0.1.0
API的版本号,默认显示在API名称的右方。该参数可用来在不同的版本之间做比较,后面会介绍。
@apiName GetUser
API名称,不影响文档。
@apiGroup User
API分组名,文档内容中和菜单栏中同一组的API会在一同显示,方便阅读。
@apiPermission admin
API的访问权限,文档中默认会API地址下面显示。没有权限要求的话,此项可以省略。
@apiDescription API to get the user information.
API的详细描述,默认显示在API名称的下方。
@apiExample Example usage:
API调用示例,该参数的下一行就是示例的内容,直到有空行结束。可以定义多个@apiExample,默认在文档中会以标签形式列出,标签名就是”Example usage:”。
@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍,”{Number}”定义了字段类型,”user_id”是字段名称,后面则是字段描述。可以定义多个@apiParam字段。
@apiSuccess {String} name Name of the User.
API成功后返回的字段,如同@apiParam,”{String}”定义了字段类型,”name”是返回字段名称,后面则是字段描述。可以定义多个@apiSuccess字段。
@apiSuccessExample {json} Success-Response:
显示一个API成功返回后Response响应的示例,”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容,直到有空行结束。可以定义多个@apiSuccessExample,默认在文档中会以标签形式列出,标签名就是”Success-Response:”。
@apiError UserNotFound User was not found.
API发生错误后的返回,”UserNotFound”是错误名称,后面则是错误描述。可以定义多个错误返回。
@apiErrorExample {json} Error-Response:
显示一个API错误返回后Response响应的示例,”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容,直到有空行结束。可以定义多个@apiErrorExample,默认在文档中会以标签形式列出,标签名就是”Error-Response:”。
@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后,此参数即可省去,除非这个API的测试URL比较特殊,需特别指定。