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
.