后端开发之--APIdoc的应用

前言

最近在学习后端开发，而后端开发中写好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 id of the User was not found.
*/

效果图：