puppy-api-docs/README.md

Genernate material api docs from your comments.

# puppy-api-docs

Generate beautiful api docs directly from your code comments.

## Install 

Install the package globally.
```
npm install -g puppy-api-docs
```

## Usage

Puppy api docs are very easy to use. All you have to do is write comments in your code, puppy will automatically extract them and generate minimal yet beautiful looking documentation.

Here is a simple example.

```js
/*
@docstart
{
    "title": "Login",
    "method": "POST",
    "description": "Login with email and password.",
    "path": "/login"
}
@docend
*/
router.post('/login', (req, res) => {...})
```

In any of your `js` file go ahead and create a comment as above. Make sure you add `@docstart` and `@docend`, as puppy will only read content between those tags.

Inside the start and end tags, goes a json object. You have to make sure that this json object is well formatted, else it won't be included in the generated docs.

Inside this json object you can specify various properties. Here we have only specified `title`, `description`, `method`, and `path`.

Once you are done writing the comment, in your project `root`, go ahead and run the following command.

```
puppy-generate-api
```

Puppy will automatically search all the `js` files for comments and extract the information.

The docs will be generated and saved in a folder named `api_docs`. In this folder you will find `doc.html` which contains the generated docs.

## Properties

Here are all properties supported by puppy at the moment.

```js
/*
@docstart
{
    "title": "Login",
    "method": "POST",
    "group": "Authentication",
    "description": "Login with email and password.",
    "path": "/login",
    "response": {
        "status": 200,
        "message": "Help message depending on success",
        "success": true
    },
    "request": {
        "data": {
            "email": "User's email",
            "password": "User's Password"
        }
    },
    "requestHeaders": {
        "Content-Type": "application/json"
    },
    "responseHeaders": {
        "token": "session token"
    }
}
@docend
*/
```

## Grouping
Puppy supports the concept of grouping where in you can put a bunch of api's in a particular group.

So suppose you can put login and sign up api's in a group named `Auth`. All you have to do is specify the `group` property in the comment.

Example.

```js
/*
@docstart
{
    "title": "Login",
    "group": "Auth",
    "method": "POST",
    "description": "Login with email and password.",
    "path": "/login"
}
@docend
*/
router.post('/login', (req, res) => {...})

/*
@docstart
{
    "title": "Sign Up",
    "group": "Auth",
    "method": "POST",
    "description": "Sign up with email and password.",
    "path": "/signup"
}
@docend
*/
router.post('/signup', (req, res) => {...})

/*
@docstart
{
    "title": "Get Todos's",
    "method": "GET",
    "description": "Get a list of all todos for a user.",
    "path": "/todos"
}
@docend
*/
router.get('/todos', (req, res) => {...})
```

Here you can see that we have provided a group value in both `login` and `signup` api. In the third api, `/todos` we han't provided any group. By default if you don't provide a group, the generated api doc will fall under a common group named `API's`.