@grava.io/api-doc

@grava.io/api-doc is a module that allows you transform commented documentation into markdown formatted documentation. Make comments in the code and export an markdown documentation!

Install from npm

npm install -g @grava.io/api-doc

Run

Help:

api-doc --help

Result:

Usage: api-doc [options]

Transform commented documentation into markdown formatted documentation

Options:
  -V, --version        output the version number
  -f, --files <path>   Folder to analize
  -o, --output <path>  Output path to save markdown documentation. If is not defined, it will print on console
  -h, --help           display help for command

Route definitions format

The definitions must be inside a "comment" with this format:

/*

*/

To make it preattier we use this convention:

/**
 * definition_line
 * definition_line
 * definition_line
 */

Inside this structure you can use different type of definitions:

Name

In this definition you must define a title for your route.

Format:

@name ROUTE_NAME

In example:

@name List user posts

Description

In this definition you must define a more specific description for your route.

Format:

@description ROUTE_DESCRIPTION

In example:

@name In this route you can get all post of an specific user. You must send a userId and you can filter post by some fields.

You can use multiple lines in description. In example:

@description First line in description
@description Second line
@description - an item
@description - another item

Route

In this definition you must define a the method and path for your route.

Format:

@route {ROUTE_METHOD} ROUTE_COMPLETE_PATH

In example:

@route {GET} /users/:userId/posts

Parameters

With this definitions you can specify the parameters of the route (both required and optional). There are 4 types of parameters, but all have the same format:

@PARAMETER_TYPE (optional) {PARAMETER_FIELD_TYPE} [PARAMETER_FIELD_NAME] PARAMETER_FIELD_DESCRIPTION

with this options:

• PARAMETER_TYPE: could be "headerparam", "urlparam", "queryparam", "bodyparam"
• (optional): it says that the parameter is optional. If the parameter is requered don't include this
• PARAMETER_FIELD_TYPE: the data type of the field. In example: "string", "number", "date", "array", "object"
• PARAMETER_FIELD_NAME: the name of the field
• PARAMETER_FIELD_DESCRIPTION: a description of the field. Here you can explain posibles values, validations, etc

Examples of each parameter type:

headerparam

@headerparam {string} [Authorization] JWT token

urlparam

@urlparam {string} [userId] The user identifier

queryparam

@queryparam (optional) {date} [dateFrom] filter the results after this date
@queryparam {string} [category] filter the post category. Posibles values: "sports", "memes", "music"

bodyparam

@bodyparam {number} [age] User age
@bodyparam (optional) {string} [address] User full address with street, number and postal code

Responses

With this definitions you can specify the posible responses of the route (with status). Inside this definition you can spicify the body response.

Format:

@response {RESPONSE_STATUS} RESPONSE_TITLE

In example:

@response {201} User information was succesfully

or

@response {400} Invalid field value

Response body

After a "response" line you can add "responsebody" definitions. IMPORTANT: the responsebody definitions must be following the response definition.

Format:

@responsebody {RESPONSE_FIELD_TYPE} [RESPONSE_FIELD_NAME] RESPONSE_FIELD_DESCRIPTION

In example:

@responsebody {number} [age] User age
@responsebody {string} [address] User address

Examples

You can find some examples in the "examples" folder

Development

Instal dependencies

npm i

Run in local with

./bin/api-doc

In example, to run examples folder

./bin/api-doc -f ./examples/

Release

1. Change version in package.json.
2. Merge to main and push to github
3. Tag the commit (use the correct version)

   git tag -a v1.2.0
   

4. Publish to npm

   npm publish
   

5. Push tag to github