前言
最近在学习后端开发,而后端开发中写好Api文档是十分重要的一部分,所以写下这篇博客,一个是推荐ApiDoc这个工具,另一个是加深自己对其的理解。
链接
解析一
全局安装apidoc
npm install apidoc -g
创建一个文件夹如myapp 新建文件example.js文件
example.js
var currentUser = {
name: 'Mary'
};
/**
*@api{post}/user Post User information
*@apiName PostUser
*@apiGroup User
*
*@apiSuccess {String} name The users name
*
*@apiSuccessExample Example data on success:
*{
* name:'Paul'
*}
*/
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};
}
在当前目录运行命令 apidoc
出现: info:Done后,
点开当前目录生成的doc文件,运行index.html即可
效果图:
解析二
根文件夹新建文件_apidoc.js
测试版本比较功能
这个功能实际的作为:
如果你要修改一个API文档,你可以把老的API放到_apidoc.js中,然后尽情修改你新的api,
大家也能够看到你修改的地方
_apidoc.js
/**
*@api{post}/user Post User information
*@apiName PostUser
*@apiGroup User
*@apiVersion 0.1.0
*
*@apiSuccess {String} name The users name
*
*@apiSuccessExample Example data on success:
*{
* name:'Paul'
*}
*/
example.js
var currentUser = {
name: 'Mary'
};
/**
*@api{post}/user Post User information
*@apiName PostUser
*@apiGroup User
*@apiVersion 0.2.0
*
*@apiSuccess {Number} age Calculated age from Birthday
*
*@apiSuccessExample Example data on success:
*{
* 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};
}
效果图
到这里我们应该对apiDoc有一定的了解了,
官网中给出19中关于apiDoc的参数,即@之后的变量。
这里我们以实际例子挑几种讲一下~ 能够写出一份好看的Api文档就行了,剩下的根据需求再看~
@apiGroup
@apiVersion
@api 方法, 路由, api名称
@apiDescription
@apiParam {参数类型} 参数名 参数描述
@apiSuccess {参数类型} 参数名 参数描述
@apiSuccessExample
@apiError
example.js
/**
*@apiGroup ApiGroupName
*@apiVersion 0.1.0
*@api {get} /user/:id this is the apiName
*@apiDescription This is the Api Description.
*@apiParam {String} id id of the user
*@apiSuccess {String} firstname Firstname of the User.
*@apiSuccessExample {json} Success-Response:
* { "content": "This is an example content" }
*@apiError UserNotFound The <code>id</code> of the User was not found.
*/
效果图: