后端开发之--APIdoc的应用

前言

最近在学习后端开发，而后端开发中写好Api文档是十分重要的一部分，所以写下这篇博客，一个是推荐ApiDoc这个工具，另一个是加深自己对其的理解。

链接

这里是官网

解析一

全局安装apidocnpm 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.*/

效果图：