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