What is "apidoc" ?
Apidoc is a package to create documentation for api from notes in your source code.
Where can i use it?
The service is compatible with any programming language that allow block documentation.
How can i use ?
First of all you need to configuring the environment:
install node from the link "https://nodejs.org/en/"
install apidoc by command line below:
"npm install apidoc -g"
Now we can start configure the project:
- install grunt-apidoc "npm install grunt-apidoc --save-dev"
Grunt is a task generator to apidoc
-
On your root of your project you need to create a "Grunfile.js"
- In your Gruntfile you need to add the options below to config the destination path to apidoc:
apidoc: {
myapp: {
src: "app/",
dest: "apidoc/"
}
}
- After that you need to create a file called "apidoc.json" to include information about your project:
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
Obs:. this file is optional, it is just to describe your project, and you can add this config in your package json if it's a node project, but I preffer a separated file.
Now we can start making documentation.
To start you just need to comment before your endpoint like below:
/**
* @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"
* }
*/
```
###Let's generate the documentation with the command bellow:
```
"apidoc -i myapp/ -o apidoc/ -t mytemplate/"
```
We need to pass in the command three arguments, first the folder where we can search the comments, second the output and in the end if we make a template the path to template, the final result is the image below:
![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/h4dbhol10xri3kac2nfh.JPG)
This is my first post on dev.to, I hope it was of any help, any questions or suggestions just comment below!
![Alt Text](https://media.giphy.com/media/3o6fJ1l3Wr1ugMu1Rm/giphy.gif)
Top comments (6)
Nice and simple walkthrough. Thank you.
Great post dude π€©
Thanks man! βπ
I think it's awesome to have such package, i never imagined we could do such a thing. Thanks for sharing! π
thanks for your post I do this steps but I get an error that I cannot solve it maybe you can help me
Hey, sorry for delay, how can i help you?