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
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 /*@docstart{ "title": "Sign Up", "group": "Auth", "method": "POST", "description": "Sign up with email and password.", "path": "/signup"}@docend*/router /*@docstart{ "title": "Get Todos's", "method": "GET", "description": "Get a list of all todos for a user.", "path": "/todos"}@docend*/router
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
.