Sunday, October 30, 2011

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.

Saturday, October 15, 2011

Generating pdf out of html using Java

I had this requirement of generating PDF out of HTML content. Users can add any kind of html content on a Rich text editor from few lines to a full paragraph as notes for a file and save it on the server. Now I had to notify other users when some user adds a note. Now in the past I have generated PDF for reports but that was on a structured data straight out of database so I could easily use something like itext or jasperreports but  this one seems an interesting problem as user can do any free form html in the editor.

Ultimately the solution came to be:
  1. Convert the html added by user into xhtml using JTidy
  2.  Use flying saucer's ITextRenderer (http://code.google.com/p/flying-saucer/) to generate the pdf out of xhtml.
Here is a sample code



public class TextSectionConverter {

 private String notesContent;

 public TextSectionConverter(String notesContent) {
  this.notesContent = notesContent;
 }

 public void writeAsPdf(FileOutputStream fos)
   throws Exception {
  convertToXHTML();
  ITextRenderer renderer = new ITextRenderer();
  renderer.setDocumentFromString(notesContent);
  renderer.layout();
  renderer.createPDF(fos);
 }

 void convertToXHTML() throws Exception {
  notesContent = "" + notesContent + "";
  StringWriter writer = new StringWriter();
  Tidy tidy = new Tidy();
  tidy.setTidyMark(false);
  tidy.setDocType("omit");
  tidy.setXHTML(true);
  tidy.setInputEncoding("utf-8");
  tidy.setOutputEncoding("utf-8");
  tidy.parse(new StringReader(notesContent), writer);
  writer.close();
  notesContent = writer.toString();
 }