api-annotation

api-annotation

like java annotation, using comments annotation, generate both router binding script and apidoc

cli usage

api-annotation -o auto_router.js --doc ./document --api-version 1.0.0

programmable

var apiAnn = require('api-annotation');

apiAnn.process(dir, (err, data) => {

  // gen router file
  apiAnn.genRouter(data, {

  }, (err) => {
    /**
     * optional, only if you need custom the output router file
     */
    tpl: function(data) {},
    routerFile: '', // router_file_path
    version: '' // api version
  });

  // gen api document
  apiAnn.genDocument(data, {
    docPath: '',
    version: '',
    hook: () => {} // optional
  }, (err) => {

  });
  // gen api list json
  apiAnn.genApiList(data, {
    apiListPath: '',
    version: ''
  }, (err) => {

  });
});

Syntax

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) {

};

@api [required]

define the api path and support method

// full pattern
@api {method} /url

// in short, default method is `GET`
@api /url

@name [optional]

name and group the api, just for display in apidoc

@name groupName.apiName
@name group0.group1.groupXXXX.apiName

@description / @desc

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

@query [optional]

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 [optional]

@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-type when query this api
• pay attension to the indention, it means sub properties

test

# run test
npm test

# create syntax case
make syntaxCase case=00x

Appendix: all annotation token

@api
@name
@json
@description
@desc
@params
@query
@body
@success
@failure
@error
@private
@internal
@public
@disable