Documenting Groovy services with Groovydoc

Groovydoc is the Groovy counterpart of the Javadoc; it is used to provide the API documentation of Groovy type, field, property, and method definitions. It follows Javadoc's syntax.

In Martini, Groovydoc also serves to document web APIs exposed via Groovy services. They are handy for expressing the purpose of an endpoint, the inputs it expects, and the possible outputs of the endpoint. This makes it easier for the users of the API to grasp how to use the API, as well as for developers to improve and push modifications (related) to the endpoint.

A doc comment in Groovy must:

• precede a class, field, constructor, or method; and
• begin with /** and end with a */.

By convention, each new line in a Groovydoc comment starts with an *. For example:

/**
 * Greet API.
 */
@RestController
@RequestMapping(value = 'greet', produces = ['application/json', 'application/xml'])
class GreetingController {

    /**
      * Say hello to an entity.
      *
      * @param name the name of the entity to greet
      * @return a greeting
      */
    @RequestMapping(value = 'hello', method = [RequestMethod.GET])
    APIResponse sayHello(@RequestParam String name) {
        new APIResponse("Hello, $name!")
    }

}

During compilation, Martini's built-in customized compiler configuration prompts the implicit inclusion of @Documented annotations. Comments are ignored during compilation but using this annotation which wraps Groovydoc comments, we will be able to re-use the comments and port them implicitly to Swagger annotations. These Swagger annotations in turn, help us create Swagger-based API definitions.

Implicit annotation declarations

Though the compiler adds annotations during compilation, the source code will remain unaffected because these changes are reflected only at the bytecode-level.

With the code above, the API definition displayed in API Explorer would look more or less the same as below:

The service invoker would also get updated so that it displays those comments:

Use the groovydoc command to generate HTML documentation

You may generate HTML documentation pages (based on the comments you've written) via the groovydoc command. Using this, however, would require file system access to the Groovy scripts or classes.