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.

/*
@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.

/*
@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.

/*
@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.