2

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:

  1. Produce some HTML documentation from javax.ws.rs annotated code.

  2. Javadoc already written for the API and parameters and exceptions should be incorporated into the generated docs.

  3. 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:

  1. 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.

  2. An interactive editor for the above.

  3. 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?

Improve this question
4
  • Why would you not just use Javadoc?
    – ericg
    Feb 24, 2016 at 20:31
  • Documenting the REST API, not the Java API. The two are mapped together with annotations (the javax.ws.rs bit). I want to take what I can form the javadoc, and produce some nice REST API documentation from that.
    – user2800708
    Feb 24, 2016 at 21:54
  • Any more recommendation?
    – user2800708
    Feb 29, 2016 at 14:36
  • I'm thinking something that uses swagger, but not found the right tool yet that does good docs for humans with examples and so on and swagger too.
    – user2800708
    Feb 29, 2016 at 14:37

2 Answers 2

Reset to default
1
+50

MireDot is designed for this.

  • Input: Jax-rs, Spring Web-mvc, Jackson code/configuration files
  • Output: HTML and RAML among other options

Requirements 1/2/3 are fulfilled but optional requirements 4/5/6 only partly, in particular the output is read-only.

Example HTML output: http://miredot.com/exampledocs/

It is free for open source projects.

Note: I haven't tried it myself.

Improve this answer
2
  • Founder of Miredot here. Requirements 4/5 are indeed only partly covered. You can add an introductory paragraph in html and in order to add examples, you can of course use html layout inside Javadoc. For req 6, we do have RAML output. Swagger will probably follow in the coming months.
    – bertvh
    Feb 29, 2016 at 8:12
  • @bertvh: Thanks! Please let me know when Swagger and other features asked by the asker become available, I will update the answer.
    – Nicolas Raoul ♦
    Feb 29, 2016 at 8:16
1

I would take a very close look at:

doxygen

  1. It can generate HTML, LaTex, RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages

  2. It supports Javadoc style documentation

  3. It is a powerful and mature product which is capable of producing good documentation out-of-the-box. However, it does have a learning curve that you will need to climb depending on exactly what you want.

Improve this answer
3
  • 1
    A surprising answer. Does doxygen do REST API documentation?
    – user2800708
    Feb 24, 2016 at 21:53
  • Eric, could you please link to the Doxygen documentation explaining how to generate documentation for either Spring MVC or javax.ws.rs REST APIs? Thanks!
    – Nicolas Raoul ♦
    Feb 25, 2016 at 8:10
  • It would help if you could update your question with (1) example(s) of how your code either is documented or might be documented and (2) exactly what you want the generated documentation to look like.
    – ericg
    Feb 25, 2016 at 13:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.