Question

I was looking for a javadoc-like REST API documentation tool. I already documented my rest controllers in javadoc and I think it would be nice to just create an api documentation from it for the front-end developers.

I think there isn’t a tool, yet. So does someone have ideas how to accomplish this task? I thought about using the classic javadoc tool and add some spring / rest specific logic. But I’m not sure yet if I also need some special markup or what could be pitfalls. In the end I’d like to have some tool that can be integrated into the maven site lifecycle but that shouldn’t be hard to accomplish.

It may be difficult to handle inheritance: I use it a lot across REST resources but for the reader, inheritance is nothing she should care about. So sub-controllers must somehow integrate the super controllers methods but also be able to create some meaningful documentation in the context of the actual controller. I’m not sure if spring allows me to overwrite methods from super controllers but still evaluates its annotations.

I’d appreciate any hints on related projects, tools that already exists or just your experience with the javadoc-tool!

Answer 1

If you wanted to do this yourself, you could approach it like this:

1. Create an AnnotationReader implementation that scans for the various @Path annotations
2. Test that it is capable of reading the name attribute
3. Create a Maven mojo that wraps this scanning functionality
4. Add in the facility to map the regex parameters (e.g. {customerId}) into something meaningful for documentation purposes – perhaps by reading the associated Javadoc.

The annotation reader won’t have to do any modifications to the existing annotations so it should be straightforward to build up a list of the endpoint regular expressions. In combination with the Javadocs you should be able to create a useful tool. I’d certainly find it useful, and perhaps others would too.