@afaizal/apidoc-swagger

Custom package to Convert api doc json to swagger json

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
00Oct 22, 2017Feb 20, 2018Minified + gzip package size for @afaizal/apidoc-swagger in KB

Readme

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.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.