@afaizal/apidoc-swagger

    0.3.7 • Public • Published

    apidoc-swagger

    apidoc and swagger are two nice projects which are focusing on documentation of APIs. This project is a middle tier which tries to bring them together in a sense that:

    It uses apidoc to convert inline documentation comments into json schema and later convert it to swagger json schmea.

    Uses the apidoc-core library.

    How It Works

    By putting in line comments in the source code like this in javascript, you will get swagger.json file which can be served to swagger-ui to generate html overview of documentation.

    /api/foo.js:

    /**
     * @api {get} /user/:id Request User information
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam (Path) {Number} id Users unique ID.
     *
     * @apiSuccess {string}  message Success string message
     * @apiSuccess {array[]} data array data
     * @apiSuccess {String}  data.firstname Firstname of the User.
     * @apiSuccess {String}  data.lastname  Lastname of the User.
     *
     * @apiSuccessExample {json} Success-Response:
        {
         "message": "Retrieved 2 users",
         "data": [
           {
             "firstname": "Alfa",
             "lastname": "Beta"
           },
           {
             "firstname": "Layla",
             "lastname": "vexana"
           }
         ]
        }
    */
     
     
    /**
     * @api {post} /user Add new user
     * @apiName PosttUser
     * @apiGroup User
     *
     * @apiParam (Form Data) {string} fname Firstname of the User.
     * @apiParam (Form Data) {string} lname Lastname of the User.
     *
     * @apiSuccess {string}  message Success string message
     * @apiSuccess {array[]} data array data
     *
     * @apiSuccessExample {json} Success-Response:
        {
         "message": "New user already added",
         "data": []
        }
    */
     
     
    /**
     * @api {get} /user Search user
     * @apiName SearchUser
     * @apiGroup User
     *
     * @apiParam (Query) {string} keyword search this firstname or lastname.
     *
     * @apiSuccess {string}  message Success string message
     * @apiSuccess {array[]} data array data
     * @apiSuccess {String}  data.firstname Firstname of the User.
     * @apiSuccess {String}  data.lastname  Lastname of the User.
     *
     * @apiSuccessExample {json} Success-Response:
        {
         "message": "Found 1 user",
         "data": [
          {
             "firstname": "Alfa",
             "lastname": "Beta"
           }
         ]
        }
    */

    Installation

    npm install @afaizal/apidoc-swagger -g

    Current version unlocks most of the basic capabilities of both projects and improvement is in progress.

    Example

    apidoc-swagger -i example/ -o doc/

    Have a look at apidoc for full functionality overview and capabilities of apidoc.

    To read more about how swagger works refer to swagger-ui and swagger-spec for details of swagger.json.

    Gulp Module

    gulp-apidoc-swagger npm install gulp-apidoc-swagger.

    Install

    npm i @afaizal/apidoc-swagger

    DownloadsWeekly Downloads

    3

    Version

    0.3.7

    License

    MIT

    Unpacked Size

    31.8 kB

    Total Files

    7

    Last publish

    Collaborators

    • afaizal