Skip to main content

Jersey Rest API html documentation

There are various ways to generate REST api documentation but how can you do it with minimal effort. Unless you are looking into very sophisticated documentation like twitter https://dev.twitter.com/docs/api, the below should suffice. If you though however want to generate twitter like documentation then also 70% of what I highlighted would work.

Jersey by default supports WADL generation by default. WADL is machine readable rest api description simliar to what WDSL was to soap. In order to get to default wadl generated by jersey you can just call http://localhost:8080/application.wadl . This WADL is a XML document so all you need now is to render it with a stylesheet. WADL has documentation tags that can be used to document a resource byt unfortunately jersey by default doesnt generate documentation tags.

So to get real html documentation the steps are:
1) Document you rest services using Java docs for the resource class and resource method. The down side of using java docs is that you will have to write the params in the method instead of declaring them as instance vars but its much better as you can kill two birds in one shot. You get javadocs for internal devloper and html documentation for rest api consumers.
@Path("/user")
public class UserRestService extends SecureRestService {
 /**
  * Gets user by userName.
  *  
  * An example of the output json is 
  *  
  *  {"prefix":"kpatel",
  *  "userNum":11,
  *  "firstName":"Kalpesh",
  *  "lastName":"Patel",
  *  "emailAddress":"kpatel@gmail.com"}
  *
  * @param userName UserName that is to be fetched. 
  * @response.representation.200.mediaType application/json
  * @response.representation.200.example  
  * @return the user json object
  * @throws IOException
  */
 @GET
 @Produces(MediaType.APPLICATION_JSON)
 @Path("username/{username}")
 public String getUser(@PathParam("username") String userName) throws IOException {
  ....
 }
}

2) Extract Javadocs to a resource-doc file to be used by jersey wadl generator.  We would use a ant task to generate this file and place it in a path that can be read from the classpath by the running application.

    <target name="check-resourcedoc-exists">
        <available file="${basedir}/build/jersey-doc-dep/resourcedoc.xml" property="jersey.resourcedoc.present"/>
    </target>
    <target name="setup-jersey-wadl-dependencies" depends="check-resourcedoc-exists" unless="jersey.resourcedoc.present">
        <delete dir="build/jersey-doc-dep" />   
        <mkdir dir="build/jersey-doc-dep" />
        <javadoc access="public" classpathref="compile.classpath">
            <fileset dir="modules/server/src/java" defaultexcludes="yes">
                <include name="**/*.java" />
            </fileset>
            <fileset dir="modules/server/build/gen-src/java" defaultexcludes="yes">
                <include name="**/*.java" />
            </fileset>
            <fileset dir="modules/ui/src/java" defaultexcludes="yes">
                <include name="**/*.java" />
            </fileset>
            <doclet name="com.sun.jersey.wadl.resourcedoc.ResourceDoclet" pathref="compile.classpath">
                <param name="-output" value="${basedir}/build/jersey-doc-dep/resourcedoc.xml" />
            </doclet>
        </javadoc>
        <copy todir="${war.path}/WEB-INF/classes">
            <fileset dir="modules/server/resource/jersey-doc-dep">
              <include name="*.xml"/>
            </fileset>
            <fileset dir="build/jersey-doc-dep">
              <include name="*.xml"/>
            </fileset>
        </copy>       
    </target>    


3) Add static documentation for the whole app and any a grammar file. This has to be hand written. I won't desrcibe the grammar file in details but it can be used for jaxb examples using some custom jersey example tags .
This is the application-doc.xml file


<applicationDocs targetNamespace="http://wadl.dev.java.net/2009/02">
   
    <doc xml:lang="en" title="The doc for My app API">
        My app documentation. You need to fill this in.
    </doc>

</applicationDocs>


This is the application-grammars.xml file

<grammars xmlns="http://wadl.dev.java.net/2009/02"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xi="http://www.w3.org/1999/XML/xinclude">
    <include href="schema.xsd" />
</grammars>


4) Configure jersey WADL generator to read resourcedoc.xml file and generate documentation tags in the wadl.

Add an init-param to your jersey filter

            <init-param>
                <param-name>com.sun.jersey.config.property.WadlGeneratorConfig</param-name>
                <param-value>com.foo.bar.MyWadlGeneratorConfig</param-value>
            </init-param>


Add this class

public class MyWadlGeneratorConfig extends WadlGeneratorConfig {
    @Override
    public List configure() {
        return generator(MyWadlGenerator.class).generator(WadlGeneratorApplicationDoc.class).prop(
                "applicationDocsFile", "classpath:/application-doc.xml")
                .generator(WadlGeneratorGrammarsSupport.class).prop(
                        "grammarsFile", "classpath:/application-grammars.xml")
                .generator(WadlGeneratorResourceDocSupport.class).prop(
                        "resourceDocFile", "classpath:/resourcedoc.xml")
                .descriptions();
    }

}

5) Inject html generating stylesheet. You can use the two stylesheet
https://github.com/mnot/wadl_stylesheets/ or https://github.com/ipcsystems/wadl-stylesheet

I prefered the ipc one as I didnt had initial documentation for each method and this one looked more better.

Doing this was the one thing took most of the time. At the end I ended up writing my own WadlResource.
 


@Produces( { "application/vnd.sun.wadl+xml", "application/xml"})
@Singleton
@Path("application.wadl")
public final class WadlResource {

 private static final AppLogger logger = AppLogger
   .getLogger(WadlResource.class);

 private WadlApplicationContext wadlContext;

 private Application application;

 private byte[] wadlXmlRepresentation;

 public WadlResource(@Context WadlApplicationContext wadlContext) {
  this.wadlContext = wadlContext;
 }

 @GET
 public synchronized Response getWadl(@Context UriInfo uriInfo) {
  if (wadlXmlRepresentation == null) {
   String styleSheetUrl = uriInfo.getBaseUri().toString() + "wadl.xsl";
   this.application = wadlContext.getApplication(uriInfo).getApplication();
   try {
    Marshaller marshaller = wadlContext.getJAXBContext()
      .createMarshaller();
    marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    ByteArrayOutputStream os = new ByteArrayOutputStream();
                Writer writer = new OutputStreamWriter(os);
                writer.write("\n");
                writer.write("\n");
                marshaller.setProperty(Marshaller.JAXB_FRAGMENT, Boolean.TRUE);
    marshaller.marshal(application, writer);
    writer.flush();
    writer.close();
    wadlXmlRepresentation = os.toByteArray();
    os.close();
   } catch (Exception e) {
    logger.error("Could not marshal wadl Application.", e);
    return Response.ok(application).build();
   }
  }

  return Response.ok(new ByteArrayInputStream(wadlXmlRepresentation))
    .build();
 }
}
If you want twitter like documentation where you want to categorise resource 
and other stuff then all you need now is to skip step 5 and add an ant task 
to generate wadl with docs and feed it to a python program that can generate 
the html doc at build time.

Comments

  1. Hi,

    This is so wonderful. I am having hard time adding this to my project. Can you help with some more details or working code?

    -Animesh
    www.animesh.org

    ReplyDelete
  2. Hi,
    Nice tutorial. Is there anything like this available in cxf ?

    ReplyDelete
  3. Unfortunately I havent worked on cxf.

    ReplyDelete
  4. CXF has built-in support for generating WADL. You have to use some cxf-specific annotations to document parameters.
    http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-WADLAutoGeneration

    Mathieu
    http://mathieuhicauber-java.blogspot.com


    ReplyDelete
    Replies
    1. Mathieu you are missing the point. Even Jersey has a built in support for WADL documentation or you can add your customized WadlResource class.

      The intent here was to generate html documentation for REST apis that can be consumed by people who dont want to deal with wadl internals.

      Delete
    2. oops sorry - missed that point indeed. Thank you anyway for your post, didn't know how to set this up on Jersey.

      Delete
  5. Hi,
    I am using jackson-jaxrs-1.5.7.jar for my rest web service. I am using custom CustomWADLGeneratorConfig to generate resource doc. The CustomWADLGeneratorConfig has the code as follows,

    public List configure()
    Unknown macro: { List ax = generator(WadlGeneratorResourceDocSupport.class).prop("resourceDocStream", "resourcedoc.xml").descriptions(); return ax; }

    }

    Wadl file has been generated successfully. But the resource class name is missing.
    After a long search in google I found that path id attribute describes the resource class name.
    But in generated application.wadl file path has been found but id attribute (class name) is missing.
    How to get id attribute??

    Additional Information :
    Through resource-doclet.jar I made ant build to produce resourcedoc.xml.
    In web.xml I have configure to load on startup for the class CustomWADLGeneratorConfig by extending WadlGeneratorConfig.
    So when the application is up it shows application.wadl file while hitting the corresponding URL.
    Resource path is available but id (Resource class name) is missing. I didn't used any grammar or xsd.

    ReplyDelete
  6. bottom line: generating REST API documentation is a major PITA.

    ReplyDelete

Post a Comment

Popular posts from this blog

RabbitMQ java clients for beginners

Here is a sample of a consumer and producer example for RabbitMQ. The steps are
Download ErlangDownload Rabbit MQ ServerDownload Rabbit MQ Java client jarsCompile and run the below two class and you are done.
This sample create a Durable Exchange, Queue and a Message. You will have to start the consumer first before you start the for the first time.

For more information on AMQP, Exchanges, Queues, read this excellent tutorial
http://blogs.digitar.com/jjww/2009/01/rabbits-and-warrens/

+++++++++++++++++RabbitMQProducer.java+++++++++++++++++++++++++++
import com.rabbitmq.client.Connection; import com.rabbitmq.client.Channel; import com.rabbitmq.client.*; public class RabbitMQProducer { public static void main(String []args) throws Exception { ConnectionFactory factory = new ConnectionFactory(); factory.setUsername("guest"); factory.setPassword("guest"); factory.setVirtualHost("/"); factory.setHost("127.0.0.1"); factory.setPort(5672); Conne…

What a rocky start to labor day weekend

Woke up by earthquake at 7:00 AM in morning and then couldn't get to sleep. I took a bath, made my tea and started checking emails and saw that after last night deployment three storage node out of 100s of nodes were running into Full GC. What was special about the 3 nodes was that each one was in a different Data centre but it was named same app02.  This got me curious I asked the node to be taken out of rotation and take a heap dump.  Yesterday night a new release has happened and I had upgraded spymemcached library version as new relic now natively supports instrumentation on it so it was a suspect. And the hunch was a bullseye, the heap dump clearly showed it taking 1.3G and full GCs were taking 6 sec but not claiming anything.



I have a quartz job in each jvm that takes a thread dump every 5 minutes and saves last 300 of them, checking few of them quickly showed a common thread among all 3 data centres. It seems there was a long running job that was trying to replicate pending…

Email slavery

It seems I have become an EmailSlave. The first half of the day is spent in just answering to emails. There are so many emails where I am copied but I need not be. There are many emails  where its a 1-2 page email and somewhere down someone says @KP please answer this.  So it seems daily my work schedule is:
Signin to newrelic and check anomalies for 15 min. Check emails related production exception report and yes there are a ton of these report daily. Need a better tool here as this model is not scalable. I need to reduce the incoming data at me to only see relevant data like what newrelic does. May be I need to create a webapp out of these emails.Check emails for next few minutes before team callsDo team callsThen again back to checking emails until a I have taken a best shot at answering everyone waiting for my reply.Attend team meetings on Tue/Thu
Being an architect and coder at heart I don't feel satisfied at end of the day if there is nothing tangible getting done at the end.…