# 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](https://github.com/apidoc/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](https://github.com/swagger-api/swagger-ui) to generate html overview of documentation.

`/api/foo.js`:
```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](https://github.com/apidoc/apidoc) for full functionality overview and capabilities of apidoc.

To read more about how swagger works refer to [swagger-ui](https://github.com/swagger-api/swagger-ui) and [swagger-spec](https://github.com/swagger-api/swagger-spec) for details of `swagger.json`.


## Gulp Module

[gulp-apidoc-swagger](https://github.com/fsbahman/gulp-apidoc-swagger) `npm install gulp-apidoc-swagger`.