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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
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.