We have talked about Swagger, which is more of an automated way of generating documentation and is useful in most cases, but there are times when you would like to have more control over what information you document and share with users. APIdoc (http://apidocjs.com/ ) is a very simple tool that helps us generate the documentation based on annotations. It gives us a lot of control, and it is similar to JavaDocs, which developers are already used to.
To get started, install APIdoc using the following command:
sudo npm install apidoc -g
Once APIdoc is installed, we are provided with a set of parameters that can be used to define documentation.
The following code showcases use of APIdoc:
package com.packt.Microservices.calculator2;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/***** This class implements Calculator functions***/
@author packt
@RestController
public class CalculatorController
{
/***Request to add 2 numbers*/
@api {get} /add?num1={num1}&num2={num2}
* @apiName Add
* @apiGroup Calculate
* @apiVersion 1.0.0
** @apiParam {Number} num1 first number
* @apiParam {Number} num2 second number
** @apiSuccess {Number}
@GetMapping("/add")
public int addNumber(int num1, int num2)
{
return(num1+num2);
}
/***Request to subtract 2 numbers*/
@api {get} /subtract?num1={num1}&num2={num2}
* @apiName Subtract
* @apiGroup Calculate
* @apiVersion 1.0.0
** @apiParam {Number} num1 first number
* @apiParam {Number} num2 second number
** @apiSuccess {Number}
@GetMapping("/subtract")
public int subtractNumber(int num1, int num2)
{
return(num1-num2);
}
/***Request to multiply 2 numbers*/
@api {get} /multiply?num1={num1}&num2={num2}
* @apiName Multiply
* @apiGroup Calculate
* @apiVersion 1.0.0
** @apiParam {Number} num1 first number
* @apiParam {Number} num2 second number
** @apiSuccess {Number}
@GetMapping("/multiply")
public int multiplyNumber(int num1, int num2)
{
return(num1*num2);
}
/***Request to divide 2 numbers*/
@api {get} /divide?num1={num1}&num2={num2}
* @apiName Divide
* @apiGroup Calculate
* @apiVersion 1.0.0
** @apiParam {Number} num1 first number
* @apiParam {Number} num2 second numbe
** @apiSuccess {Number}
@GetMapping("/divide")
public float divideNumber(float num1, float num2)
{
return(float)(num1/num2);
}
}
Finally, add apidoc.json with basic properties, as follows:
{
"name": "Calculator App",
"version": "1.0.0",
"description": "This app is used to implement Calculator functions",
"title": "Calculator",
"url" : "https://packt.mycalculator.com/v1"
}
Now, we just need to generate the documentation, as follows:
apidoc -i /Users/kamalmeetsingh/Downloads/calculator2/ -o /Users/kamalmeetsingh/Downloads/calculator2/docs/
This will generate the documentation in the output directory. We can open index.html to view the documentation. We can deploy the documentation directory on a server to make it publicly available.
An image of the output is as follow:
This kind of documentation gives us complete control over the documentation that we are creating. APIdoc gives us some core attributes, which can be used to generate documentation.
You can see how we have used some attributes in the following:
- @api: Signature of API
- @apiName: Name of API
- @apiGroup: Group-related APIs
- @apiVersion: Versions of API
- @apiParam: Define parameters
- @apiSuccess: Response on success
Apart from the preceding ones, there are a few more important attributes to mention, which you might want to use as and when needed:
- @apiError: Error return parameter.
- @apiErrorExample: Example of an error return message, output as a preformatted code.
- @apiHeader: Describe a parameter passed to your API-Header, such as for authorization.
- @apiHeaderExample: Example showcasing the headers.
- @apiSampleRequest: Example showcasing the sample request.
You can learn more about APIdocs at http://apidocjs.com/. This can be a very powerful tool for API documentation, which allows us to provide as much detail as we would like.