Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

Documenting Groovy Services with Groovydoc

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

In TORO Integrate, Groovydoc also serves to document web APIs exposed via Groovy Sevices. 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
  • begin with /** and end with a */

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import io.toro.integrate.tracker.TrackMethod

/**
 * REST controller class comprised of 'greeting' endpoints.
 */
@RestController
@RequestMapping(value = 'greet', produces = ['application/json', 'application/xml'])
@Track(method = TrackMethod.REQUEST)
class GreetingController {

    /**
      * Given the name of an entity, greets that entity with a 'hello'.
      * 
      * @param name the name of the entity which shall be greeted
      * @return the 'hello' greeting
      */
    @RequestMapping(value = 'hello', method = [RequestMethod.GET])
    APIResponse sayHello(@RequestParam String name) {
        new APIResponse("Hello, $name!")
    }

    // More request handler methods...

}

During compilation, TORO Integrate's out-of-the-box customized compiler configuration prompts the implicit inclusion of @Documented annotations. As you know, 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 to implicitly added 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:

Groovy endpoint with documentation displayed in API Explorer

The Service Invoker UI (triggered by right clicking on a service in Coder and left clicking on Invoke in Browser) would also get updated so that it displays those comments:

Groovy endpoint with documentation displayed in Service Invoker

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. You would also need file system access to the Groovy scripts or classes.