rest2doc v0.1.1

Rest2Doc

Very simple auto-generated REST API request responses examples.

Methods

getRequestResult

REST GET request to API and return the response's content

postRequestResult

REST POST request to API and return the response's content

Examples

POST Auth

// auth.js

/**
 * @name authenticate
 * @type POST
 * @description API JWT authentication end point
 * @memberof api.v1
 * @example
 * ```
 * curl -X POST http://localhost/api/v1/authenticate \
 *  -H 'Accept: application/json' \
 *  -d '{ "username": "admin", "password": "pwd" }
 * ```
 * {{#postRequestResult}}
 * { 
 *  "url": "http://localhost/api/v1/authenticate", 
 *  "data": { "username": "admin", "password": "pwd" }, 
 *  "headers": { "Accept": "application:json" } 
 * }
 * {{/postRequestResult}}
 */
router.post('/authenticate', (req, res) => { ... });

Generation example using jsdoc2md

$> jsdoc2md auth.js | rest2doc

v1.authenticate() : POST

API JWT authentication end point

Kind: static method of v1
Example

curl -X POST http://localhost/api/v1/authenticate \
 -H 'Accept: application/json' \
 -d '{ "username": "admin", "password": "pwd" }

{
  "token": "MyJWT"
}

GET User (with bearer token)

// users.js

/**
 * @name users
 * @type GET
 * @description Get specific user info
 * @memberof api.v1
 * @param {String} :id Unique user id
 * @example
 * ```
 * curl http://localhost/api/v1/users/1 \
 *  -H 'Accept: application/json'
 * ```
 * {{#getRequestResult}}
 * { 
 *  "url": "http://localhost/api/v1/users/1", 
 *  "headers": { 
 *      "Accept": "application:json",
 *      "Authorization": "Bearer <%TOKEN%>"
 *  } 
 * }
 * {{/getRequestResult}}
 */
router.get('/users/:id', (req, res) => { ... });

Generation example using jsdoc2md

All variables defined using <% and %> will be replaced by process arguments

$> jsdoc2md users.js | rest2doc --TOKEN MyJWT

v1.users(:id) : GET

Get specific user info

Kind: static method of v1

Param	Type	Description
:id	String	Unique user id

Example

curl http://localhost:3000/api/v1/users/1 \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer <token>'

{
  "id": "1",
  "username": "guest",
  "email": "guest@example.ext"
}