like java annotation, using comments annotation, generate both router binding script and apidoc
var apiAnn = require('api-annotation'); var result = apiAnn.process(); apiAnn.genRouter('./auto_router.js', result); apiAnn.genDoc('./documents/api/v1.0/', result); controller file
// controllers/test.js/** * @api{get} /api/user/:id * @name User.getUser * @desc * * @params * id * * @query * limit{Number} maxRow in result * sortBy{String} sort field * * @body:json * user{Object} D+的用户对象 * name{String} * id{Number} */exports.hello=function(req,callback){};define the api path and support method
// full pattern @api{method} /url // in short, default method is `GET` @api /url name and group the api, just for display in apidoc
@name groupName.apiName @name group0.group1.groupXXXX.apiName you can either using @desc or @description
@desc your desc here @description your desc here besides, the content before @api will merge into desc for example:
this is a desc too @api /test @desc this is a test api the finally desc will be :
this is a test api this is a desc too the query object from url's queryString
@query username{String} the target username resourceId{Number} the resource id - each properties takes a line
- each line contains: propertyName, propertyType, description
@body is same as query
take a look at more complicate example
@body:json user{Object} Class User name{String} user nick id{Number} user id group groupName{String} group name groupId{Number} group idins the code below means:
- body is a json string, you need add mime
content-typewhen query this api - pay attension to the indention, it means sub properties
# run test npm test# create syntax case make syntaxCase case=00x@api @name @json @description @desc @params @query @body @success @failure @error @private @internal @public