npm package: @grava.io/api-doc
Description: Transform commented documentation into markdown formatted documentation
Author: Grava
Latest version: 1.2.1

# \@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<string>", "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](./examples/Readme.md)


## 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