REST API example generation using Javadoc

Abstract

Formatting and editing documentation can be a tedious process regardless of how well your documentation templates are made. Especially, keeping the code examples up-to-date can be time-consuming and error-prone. The research presented in this article describes a Javadoc extension that can be used to produce example data in combination with automatically generated API method call examples, and explains how the APIs in our implementation are organized to further ease the automatic documentation process. The primary goal is to make generating method call examples for (RESTful) web services easier. The method has been used in the implementation of a media content analysis service, and the experiences, advantages of using the described approach are discussed in this article. The method allows easier validation and maintenance for the documentation of method usage examples with a downside of an increased workload in the implementation of software components required for the automatic documentation process.