Verify JAX Doclets in Maven builds
In few words, I have a Java REST API that is defined with Jersey.
I use Enunciate to generate a Swagger JSon file. Enunciate uses Javadoc comments (and optionally some annotations) to fill-in the REST documentation. But it also supports JAX doclets for complementary information.
A doclet that is quite useful is the @HTTP one.
This tag allows to define the return codes of a REST operation. And since it makes sense for all the operations of our APIs, I wanted to add an automatic verification at build time. I searched the web for something that could do this with Maven, and after quite a long search, I found the right Checkstyle module for that.
Here is the XML snippet to insert in your POM.
<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-checkstyle-plugin</artifactId> <version>2.17</version> <executions> <execution> <id>check-rest-resources</id> <phase>process-sources</phase> <goals> <goal>check</goal> </goals> <configuration> <includes>**/I*Resource.java</includes> <checkstyleRules> <module name="Checker"> <property name="charset" value="UTF-8" /> <module name="TreeWalker"> <module name="WriteTag"> <property name="tag" value="@HTTP" /> <property name="tagFormat" value="\S" /> <property name="severity" value="error" /> <property name="tagSeverity" value="ignore" /> <property name="tokens" value="METHOD_DEF" /> </module> </module> </module> </checkstyleRules> </configuration> </execution> </executions> </plugin> </plugins> </build>
So, we use the Maven plug-in for Checkstyle.
This set of rules will only apply to classes whose name is compliant with the I*Resource pattern (this is a convention we use in our project…).
And we use the WriteTag module that verifies if a given tag is used or not in a class. The tag here is @HTTP. If we do not find it (the severity property), we raise an ERROR. If we find it (tagSeverity), we ignore it. And we apply this verification to methods only (not to classes or anything else). You should easily be able to adapt it by reading the documentation of this module.