I have been given the task of finding the best way for a large API, developed using jaxrs, to be documented for third parties. The code is currently well documented with javadoc. My question is to help identify the best approach based on my research so far, and to verify that we are going down the right path, so I am looking for input, comments or additional frameworks to look at. I am sure this is a common use case and others will have similar issues and really appreciate any input from others who are experienced with swagger and documentation.
We have requirements that:
I have considered the following frameworks, but each one seems to have some major drawbacks that either make them difficult to work with (for this project), or that I am perhaps misunderstanding.
The Swagger JAXRS doclet: Link
This maven plugin works at build time and is able to provide us with reasonable documentation based on the existing javadoc comments. However, it does not support Swagger 2.0 which may put limitations on describing headers in responses which are vital for our usecase. It is able to pick up the rest services without the need for the @Api or @ApiOperation annotations which the swagger maven plugin requires. Upgrading this to work with swagger 2.0 may be a substantial task.
The Swagger Maven Plugin: Link
The plugin creates the swagger documentation at build time based on annotations rather than comments. This would require that we go through the whole project and annotate with @Api and @ApiOperation. We may get away with some annotations being on base classes only, but for any descriptions or titles of endpoints we will need to add details within the annotations themselves. Many of these annotations seem duplicated, as for example we already have @Get or @Post but still need to also add @ApiOperation and describe the parameters which are already described in javadoc. The downfall is this will take time, and will also result in very cluttered looking code.
Swagger Core: Link
Swagger core works at runtime, which means that we are unable to strip comments out from the existing javadoc. It is easily extendable, just as the Swagger Maven Plugin is, and we could add our own reader or rules to add links and meta information (or use our own existing annotations). The downside being that descriptions for each method need to come from somewhere, so these will have to be added in (yet more) annotations which are likely to be forgotten when adding new code.
Enunciate: Link
Enunciate doesn't work for us as we need to be able to use a similar framework on .NET, and it also doesn't support JDK 8 (yet).
My conclusions so far
The swagger jaxrs doclet has been the closest to doing everything we want so far. The main issue is the lack of swagger 2.0. We need to be able to update swagger versions accordingly as other projects which will be documented together (different languages) will do. Second best for us is the Swagger Maven plugin, as with a custom runner, since this is build time, it should be possible to somehow get access to the existing javadoc comments and add these in to the produced swagger - we can probably get away with some annotations being on base classes and pulling the rest (e.g descriptions) from comments using our custom reader. Finally, the swagger core doesn't really serve our needs as we would need many more annotations which duplicate existing javadoc.
With the unknown time needed to update the swagger doclet to support swagger 2.0, I am leaning towards the swagger maven plugin with a custom reader (any tips on how to read javadoc comments from in there would be useful!). Is there any framework, or detail that I have missed which makes my conclusion inaccurate?
Everyone has their own needs, so I won't go into suggested ways to do what you're after. But you can definitely extend the swagger-maven-plugin project by creating a custom parser, which will be detected via SPI.
It's not a trivial task, but if that's what you're leaning towards, there is infrastructure to support it. Please see here: https://github.com/swagger-api/swagger-parser#extensions