There are a lot of these tools to choose from, of varying levels of quality and various models from open source to commercial.
I need to document REST apis, either Spring MVC or javax.ws.rs.
My priorities are:
Produce some HTML documentation from javax.ws.rs annotated code.
Javadoc already written for the API and parameters and exceptions should be incorporated into the generated docs.
Nice looking documentation that is easy to understand the context of what you are looking at and navigate around is preferred. We don't have the time to customize look and feel, whatever you get out of the box has to do.
And some optional extras:
Allow extra content to be added to the generated documentation, such as examples. When the documentation is re-generated, this user defined documentation should survive and remain attached to the same end-points documentation as it was written for.
An interactive editor for the above.
Generate swagger, raml, hal or other meta-data formats, and hook this up to the running service. This will primarily be used to allow users to browse the API of a running service, and possibly also to submit test-cases manually.
Which tools do you think are the best?