@softcripto/jsdoc-route-plugin

New custom tags to document ExpressJs Route.

[TOC]

Install

npm install @softcripto/jsdoc-route-plugin --save-dev

Usage

Add following line to jsdoc.js

{
    ...
    "plugins": [
        ...
        "@softcripto/jsdoc-route-plugin"
    ]
}

For more details please read

Complete Example

/**
 * This is an example of documenting route endpoint
 * 
 * @module /users
 * @route {POST} /users
 * 
 * @renders HTML
 * 
 * @post {String} email - User email address
 * @post {String} password - User secret key
 * 
 * @query {String} token - Access token
 * @query {String} session - Session id
 * 
 * @headers x-cref-token - jwt access token
 * @headers x-cref-other-key - can declare multiple keys for headers
 */

Important - The @module must be included otherwise it won't work as expected.

Define like this - @module /users.

@route

The @route tag allows you to document route endpoint.

It requires 3 parameters.

1. tag @route
2. HTTP verb (i.e. POST, GET, PUT, DELETE etc) {POST}
3. Route path /users

Example:

/**
 * @route {POST} /users
 */

Only one @route tag is expected per route document.

@post

The @post allows you to document any parameters which are passed as form field. It can be either POST or PUT request.

It requires 4 parameters

1. tag @post
2. type (i.e. String, Number, Array etc.) {String}
3. name of parameter email and
4. description write about the field description

Example:

/**
 * @post {String} email - User email address
 * @post {String} password - User secret key
 */

@query

The @query allows you to document any parameters which are passed as query string in the form of URL (i.e. ?city=NY&state=NY)

It requires 4 parameters, same as @post. Please see above.

Example:

/**
 * @query {String} token - Access token
 * @query {String} session - Session id
 */

@renders

The @renders allow you to document to tell type of output by a URL

Options: HTML|JSON|XML etc.

Example:

/**
 * @renders HTML
 */

@headers

The @headers allow you to document any parameters sent in header.

It requires only 3 parameter @headers name-of-key - description of key

Example:

/**
 * @headers x-cref-token - jwt access token
 */