Generating documentation for C++ REST APIs

Like all APIs, C++ REST APIs need to be documented. If the documentation can be written together with the code, and maybe even generated from the code, that would be ideal.
This article will explain how one can generate C++ REST documentation from code.

The tool I’ve used to generate user friendly documentation for C++ REST web services is apidoc.
With this tool, you use the custom markup primitives that it provides (similar to doxygen markup) in order to document and later generate user friendly documentation.
Let’s take a look at an example - some sample C++ code with the attached markup:

class MyRestAPI {  
public:  

    /**  
    * @api {post} test/example/ An example POST request  
    * @apiName PostExample  
    * @apiGroup Example  
    *  
    * @apiPermission none  
    *  
    * @apiParam {Number} ExampleId         Example id  
    * @apiParam {String} ExampleValue      Example value  
    *  
    * @apiSuccess (200) {String} None            Empty response  
    *  
    * @apiError (400) ERROR:MissingParameter      Parameter is missing or invalid  
    */  
    void POST_example();  
}

Let’s assume that the declaration is in a header file located in a <source_directory>. To generate the html documentation, one needs to execute the following command line:

apidoc -f h -v -i <source_directory> -o <documentation_output_dir>

After running this, you will have the following documentation generated in the output directory:

Bonus info: Usually you would want to run the documentation generation inside some continuous integration system, Jenkins, for example.
In the Jenkins report publisher, javascript is disabled by default, so to be able to view the documentation, one must run the following Groovy script:

System.setProperty("hudson.model.DirectoryBrowserSupport.CSP", "")

Generating documentation for C++ REST APIs

2017/10/08