From jackson to RAML


#1

I started to develop a new API using Jackson 2.8.8.
I have already a java representation of all the entities that I want to expose that have been implemented before starting the work on the API.
Using Jackson, I have been already able to implement a first simple API that returns a complex entities with many properties and sub entities.
I would like to document the API using RAML and I am wondering if there is a simple way to generate it directly from the java classes with Jackson annotations.
I know that there is a maven plugin and a CLI that can generate the .raml starting from the compiled classes, but when I tried it, I got an “empty” definition:

#%RAML 1.0
title: Raml API generated from classes
version: 1.0
baseUri: http://www.baseuri.com
mediaType: "/"
types:

I have compiled jaxrs-to-raml-cli using its maven build and I have executed the following command:

java -jar ./target/jaxrs-to-raml-cli-2.0.1-SNAPSHOT-jar-with-dependencies.jar -a /target/classes/ -o /tmp/test.raml

Is it possible to use jaxrs-to-raml-cli (and the maven plugin) with classes annotated with Jackson? If yes, why the tool is not finding any class ?


#2

Hi… I am going to try to convince you to think the other way around on this. I hear you that you already started a first attempt using Jackson, etc. I am not entirely sure what that means… did you define JSON Schema for the entities? Did you implement it using JAXRS, or some other Rest framework? Are you using JAXB with your Jackson defined classes (assuming you are not using JSONScheam2Pojo to generate Jackson pojos)?

There is a reason for me saying this. I see a lot of teams with already built APIs with Jackson/JSON annotations, JAXRS code, etc. I worked with a group that had a decently sized API already working, and it took me only a few days of time to reverse it into a full RAML defined API with JSON Schema… that I then used the RAML 2 JAXRS project to generate the Jackson pojos, JAXRS interfaces, and implementation of those interfaces. Literally, a few days time. The result… I now had a single source of truth set of files… with documentation in place, and able to generate docs, service code, DTOs (Pojos), and if I wanted, could use ABAO to mock the service, and more. The great thing is, it is now super easy to add some resources, regenerate everything without any of my code breaking except any existing resources I already implemented that I modified the API for (e.g. perhaps I change the method type from GET to POST or added a query parameter to the definition of a resource).

If you are fortunate enough to do this with RAML 1.0, things are even nicer. More modular, custom annotations, RAML Types (instead of JSON Schema), re-usability and more.

It is, however possible to continue down the path you are on… use JAXRS to RAML, once you get it configured and set up your source files correctly to utilize it, then generate HTML docs, etc. I just find that the code is a much more difficult place to define API documentation, examples, and otherwise use as the single source of truth for the API itself. I also find that other than developers, sharing/explaining/teaching the API is not as easy… you cant just share the RAML file and work with the API designer and modify the file and see the changes occur in real time. You have to modify code, update javadoc, then generate a RAML file, etc. To each their own I guess, but having done it both ways, I can atest that RAML first, then code/doc/artifact generation is easier to work with, faster to collaborate with and easier to manage as well.


#3

Thank you for your answer Kevin. What you say makes perfect sense.

Unfortunately, my question was inaccurate. I am using a framework (called spring-webscripts) to implement the REST APIs. I am using Jackson only to generate the json representations for the output and to parse the json representation in input.

I had to use a workaround to be able to use the jax-rs-to-raml tool. For now, I am more interested to produce the description of the types because they are complex and it would be difficult to manually write their definition.
Because using Jackson I am able to correctly generate the desired json, I was expecting to be able to generate also its formal definition.
I continued to play with it and I am able now to produce an almost complete raml description of the types, but I had to fix some issues in the tool that was failing every time a generics was used in my classes.
Often in the code, the jax-rs-to-raml tool tries to do something like:

public void scanType(TypeRegistry typeRegistry, RamlEntity type, RamlType ramlType) {

    Class c = (Class) type.getType();
    forFields(typeRegistry, type, ramlType, c);
    forProperties(typeRegistry, type, ramlType, c);

The cast to Class throws an exception when the type that I am trying to document contains a generics, like for example: Predicate<Element>.

Do you know if this is a known limitation ?