DEV Community

Anurag Gupta
Anurag Gupta

Posted on • Updated on

API Documentation Made Easy

As this is my first technical blog, so I'm pretty excited for this one.

How can you document your API without any hassle?

We all know that its very easy for us developers to code things out but when it comes to documentation, it feels really uninteresting and a boring job, I don't know is it just me.

I recently came across this NPM package and was mind blown.

API Link - apiDOC

Why to use this for documentation?

The documentation of this package is really clear and concise, but ill just put out few points which I really liked about apiDOC.

  • Very easy to get started with.

  • Implementation is very simple, and it makes the code understandable. Look at the code snippet you'll get some idea how this can be implemented just by adding some lines as a comment. There are various params being used, do check them out in the documentation. This makes API documentation an easy and simple task.

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
Enter fullscreen mode Exit fullscreen mode
  • It automatically generates the API documentation with an amazing UI. You can refer the demo given below. Isn't it amazing?

Link to demo

image.png

  • It supports various languages like Java, JavaScript, PHP, Perl, Python, Ruby, Lua, and many more.

If you gained some value from this blog, please share it with your fellow developers and help them grow as well. Peace!

Let's connect,
Follow me on Twitter - Twitter

Top comments (2)

Collapse
 
anurag5086 profile image
Anurag Gupta

Deepfakehttp looks nice ill try it out! Thanks for the comment!

Collapse
 
anurag5086 profile image
Anurag Gupta

Yeah Openapi is much popular. Thanks for the comment!