Web API文档生成工具apidoc

npminstallgrunt-apidoc--save-dev

Gruntfile.js

grunt.loadNpmTasks('grunt-apidoc');

grunttask

apidoc:{
myapp:{
src:"app/",
dest:"apidoc/"
}
}

//在sails中2和3可以直接添加一个task

module.exports=function(grunt){

grunt.config.set('clean',{
apidoc:{
myapp:{
src:"app/",
dest:"apidoc/"
}
}
});

grunt.loadNpmTasks('grunt-apidoc');
};

用法

shell

apidoc-h

//典型用法
apidoc-iapi/-odoc/api[-c./]-f".*\.js$"

-i表示输入，后面是文件夹路径
-o表示输出，后面是文件夹路径
默认会带上-c，在当前路径下寻找配置文件(apidoc.json)，如果找不到则会在package.json中寻找"apidoc":{}
-f为文件过滤，后面是正则表达式，示例为只选着js文件
与-f类似，还有一个-e的选项，表示要排除的文件/文件夹，也是使用正则表达式
如果项目输入和输出稳定，可以编辑Makefile保存命令，例如：

docs:
@apidoc-iapi/-odoc/apidoc

makedocs

配置

项目配置

apidoc.json

{
"name":"mysails",
"version":"1.0.0",
"title":"mysails",//浏览器标题
"description":"xun'stestproject"
}

package.json

package.json

apidoc

{
"name":"mysails",
"private":true,
"version":"1.0.0",
"description":"xun'stestproject",
"apidoc":{
"title":"mysails"
},
...
}

代码注释

apidoc

@api{method}path[title]
只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单
method可以有空格，如{POSTGET}
@apiGroupname
分组名称，被解析为导航栏菜单
@apiNamename
接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
@apiDescriptiontext
接口描述，支持html语法
@apiVersionverison
接口版本，major.minor.patch的形式

@apiIgnore[hint]
apidoc会忽略使用@apiIgnore标注的接口，hint为描述
@apiSampleRequesturl
接口测试地址以供测试，发送请求时，@apimethod必须为POST/GET等其中一种

@apiDefinename[title][description]
定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块
在@apiDefine内部不可以使用@apiUse
@apiUsename
引入一个@apiDefine的注释块

@apiParam[(group)][{type}][field=defaultValue][description]
@apiHeader[(group)][{type}][field=defaultValue][description]
@apiError[(group)][{type}]field[description]
@apiSuccess[(group)][{type}]field[description]
用法基本类似，分别描述请求参数、头部，响应错误和成功
group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample[{type}][title]example
@apiHeaderExample[{type}][title]example
@apiErrorExample[{type}][title]example
@apiSuccessExample[{type}][title]example
用法完全一致，但是type表示的是example的语言类型
example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)

@apiPermissionname
name必须独一无二，描述@api的访问权限，如admin/anyone

200

/**js
*@apiDefineCODE_200
*@apiSuccess(Reponse200){number}code200
*@apiSuccess(Reponse200){json}[data='""']如果有数据返回
*@apiSuccessExample{json}Response200Example
*HTTP/1.1200OK
*{
*"code":200,
*"data":""
*}
*/

500

/**
*@apiDefineCODE_500
*@apiSuccess(Response500){number}code500
*@apiSuccess(Response500){string}[message]errordescription
*@apiSuccessExample{json}Response500Example
*HTTP/1.1500InternalServerError
*{
*"code":500
*"message":"xxx"
*}
*/

/**
*@apiDefineData
*
*@apiParam(data){string}[firstname]OptionalFirstnameoftheUser.
*@apiParam(data){string}lastnameMandatoryLastname.
*@apiParam(data){string}country="cn"Mandatorywithdefaultvalue"DE".
*@apiParam(data){number}[age=18]OptionalAgewithdefault18.
*/

/**
*@api{POSTGET}/api/test/hello[/:id]/api/test/hello[/:id]
*@apiNametestapi
*@apiGroupHelloWorld
*@apiVersion1.0.0
*@apiDescriptionjustatest
*@apiPermissionanyone
*@apiSampleRequesthttp://test.github.com*
*@apiParam{number}[id]anyid
*@apiParam{json}dataobject
*@apiUseData
*
*@apiParamExample{json}RequestExample
*POST/api/test/hello/1
*{
*"data":{
*"firstname":"test",
*"lastname":"sails",
*"country":"cn"
*}
*}
*
*@apiUseCODE_200
*@apiUseCODE_500
*/