Rest2Doc

Very simple auto-generated REST API request responses examples.

Methods

| Parameter | Type | Description | | --- | --- | --- | | url | string | REST API End point url | | headers | object | JSON Object containing HTTP request headers |

getRequestResult

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

postRequestResult

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

| Parameter | Type | Description | | --- | --- | --- | | data | Any | POST Request data |

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": "[email protected]"
}