JAXRS analyzer, documenting your REST API an alternative. #swagger #javaee #jaxrs #maven

Lately, I have been considering using Swagger (core and it's related maven plugin) for one project, in order to provide some REST API documentation.

Despite the fact, that Swagger is indeed a very powerful library, doable to integrate on your JAXRS 2.0 code base and the maven plugin works at the end of the day I think that the extra annotations on my code (my JAXRS resource classes) were creating an annotation mess. My classes ended up difficult to read and maintain, at least for me. Maybe I am getting tired lately with the annotation overload.

Recently, through Adam Bien's blog, I discovered JAXRS-analyzer, a project by S.Daschner and it's maven plugin . There is zero impact on extra annotations, completely compatible with my code base, fast and simple. Eventually it can output, swagger compatible json files, and then feed it to your swagger config and end up with a proper swagger based documentation site. For the time being I am not using this function rather than producing either AsciiDoc or plain text Rest API doc.

Of course there is still way to go and I am sure he will be adding features, but at the time being I consider it production ready for providing fast enough, some documentation to your API consumers. Give it a try.

Well done!