Resteasy - generate REST documentation from Javadoc and Annotations

Question

I would like to find a way to generate nice REST API documentation out of java code (WADL or HTML) - based on JAXB, JAX-RS annotations and java doc comments (no doclet please).

Here is my project environment

• Spring, no XML only annotations
• Rest-easy as REST provider
• JAXB and JAX-RS annotations
• Mime Type for rest API in JSON

Solution 1

Try Enunciate.

Enunciate is an engine for dramatically enhancing your Java Web service API. It's simple. You develop your Web service API using standard Java technologies and attach Enunciate to your build process. Suddenly, your Web service API is boasting some pretty impressive features:

• Full HTML documentation of your services, scraped from your JavaDocs.
• Client-side libraries (e.g. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT, etc.) for developers who want to interface with your API.
• Interface Definition Documents (e.g. WSDL, WADL, XML-Schema, etc.)
• Etc.

Solution 2

As an alternative to Enunciate, you might also consider MireDot. It grew from a tool we use within our own company and it's free to use for open source projects. It does exactly what you describe: it combines jaxrs annotations and existing javadoc comments to generate a rest api. It works as a maven plugin which you just have to add to your project. Jaxb annotations are not yet supported at the moment of writing, but the tool is under active development and we pick the features to implement based on suggestions/requests/feedback.

Solution 3

The Java Compiler APIs allow you to write code that parses Java source and perform your own processing.

Here's an instructional article, which includes information about parsing annotations.

I guess that you can extract the raw information you need using these APIs. However this is going to yield syntactic facts - the REST URLs and actions and parameters, a user would also benefit from additional explanation, which the service author could (should?) provide in Java Doc.

the full solution might be to parse both annotation and java doc and combine the two.

Comments

[Maciej Miklas]

right.... but I would like to have more like maven plugin which would handle this for me - and ONLY doc generation, no client lib or something like that.

[djna]

I guess I'm assuming that a plugin does not yet exist, and suggesting how one could be written. My recommendation would be just to use JavaDoc.

[thermz]

Tried MireDot just now, and it's REALLY GOOD!

[jav_000]

I have used MireDot with RestEasy and is really cool and easy to configure

[Admin]

The only "problem" with MireDot is the required license key. One per artifactId... (even for the free part)

[ybonda]

Cannot find it on the web. Anyone?

[vim]

Can be found at github.com/stoicflame/enunciate