Guest Post: Automatically documenting existing JAXRS APIs with RAML

Category : uncategorized

Steven Butt is a Senior Software Engineer working on cloud platforms at MuleSoft. He moonlights as an advocate for API cleanliness.

As a web platform engineer I found myself very excited when the RAML API definition language first came onto the scene. Finally there was simple programmatic method to design and document APIs and then use that same design to drive mockups and real implementation. However, like most engineers at companies with existing Java web applications in production, I already own a large suite of active public and private APIs that need documentation, updating, and quite often new features added. How was I supposed to go from my existing Java code (implemented with Jersey JAX-RS) to a complete set of RAML files with full API definitions, schemas, and examples? Manually typing out RAML files was not the best option due to the large number of existing API resources. Believe me, I tried.

That’s why I’m so excited about the recently released JAX-RS to RAML generator tool. Now with a few button clicks I can extract my Java API implementation code into a fully featured RAML specification that can be viewed or edited in the slick API Designer or published as documentation for other developers to help them build their own applications on top of the APIs. The generator works by scanning through your Java code to look for packages and classes that have appropriate RESTful code annotations and then transferring that information into RAML. Details of how your APIs work such as resource paths, query parameters, media types consumed or produced, etc. will appear in the RAML output. The tool will even recognize extended JAX-RS annotations such as @ApiResponse and @ApiError and include those values in the generated RAML.

 The generator tool is available in several different forms including an Eclipse GUI plugin, command line interface, and a runtime plugin, so you may pick the one that works best for your needs. Today I will show you how to use the Eclipse plugin to generate RAML from a simple Java API implementation. The first thing you’ll want to do is install the RAML GUI plugin using the “Install New Software” feature of Eclipse. In the bar where you specify the update site you should enter http://raml-tools.mulesoft.com/jaxrs-to-raml/eclipse and that should give you the following dialog window of available tools.

Check the boxes next to the RAML Tools and click Next until the package installs and you are prompted to restart Eclipse. After restart you’ll have the tool available for use.

Now that we have the tool installed, let’s run it on some existing Java code that implements a RESTful API and see what happens. For the purpose of this exercise I have created a simple Java package with an interface for a customer API.

As you can see, this API provides an interface for performing very common customer operations. We can retrieve a list of customers with a GET request to /customers or retrieve just a single customer with a GET request to /customer/{id} where {id} is the id number of the customer in our business database. We can create a new customer in the system by performing a POST request to the URI /customers. We can also update an existing customer by doing a PUT request to /customers/{id}. Finally, we can delete a customer from the system entirely by performing a DELETE request to the same /customers/{id} URI. All input/output to the API is done through Customer objects described in the Java class definition. Note that I include XML code annotations that will drive both the XML and JSON schema definitions for this class in the output RAML.

So, now that we have our Java REST API classes and the Eclipse JAX-RS to RAML generator tool installed, we may now generate the complete RAML file for our API. To do so, select the Java class or the entire package in the package explorer window and right-click. In the popup dialog box you should see “Generate RAML from classes” as one of the options next to the profile, debug, and run options. Select it to be taken to the next options dialog window.

From the Generate RAML dialog window you may select various options to customize the output files. From the basic settings window you can enter the RAML output file name, API title, version number, and base URL to use. You may also select options to sort the resources alphabetically and whether or not to combine schemas and examples into a single RAML file or keep them separate. From the response codes window you may set default REST response codes for different kinds of methods in your API. If the parser cannot determine the exact response code from your JAX-RS annotations, then the tool will infer the response code from the defaults you set. In my example I have entered what I would normally return for the associated methods.

Now that I have all of my options set I can click OK and a few seconds later the RAML, schema, and example files are all written to my output folder. Then I simply copy and paste the RAML output to the Anypoint Platform API Designer tool for any last-minute modifications or enhancements before publishing the API definition to an internal or external site for consumption. You can see an image of my sample output API below. Note that all of the resources and methods defined in my JAX-RS API are visible on the right side bar and clicking on any of them will bring up the relevant details such as query parameters, response codes, etc.

That’s all there is to it!  With the JAX-RS to RAML generator we now have a frictionless path for taking existing Java APIs and creating matching RAML files to create a common standard for your existing APIs, identify common patterns and drive API adoption.  Check it out and leave some feedback on your experiences applying the tool to your use cases.  Of course, if you’re going the other way and have RAML files but no implementation you should definitely try the RAML to JAX-RS code generator.  Once you define your API specification for your existing APIs you create a developer portal using API Developer Portal.