Nanobots Protecting Microbots

    api-annotation

    1.0.2 • Public • Published

    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
    

    Keywords

    none

    Install

    npm i api-annotation

    DownloadsWeekly Downloads

    28

    Version

    1.0.2

    License

    none

    Unpacked Size

    235 kB

    Total Files

    19

    Last publish

    Collaborators

    • fish
    • fishbar