RAML to JAX-RS with POJOs from Schemas


#1

Hi,

I’ve briefly taken the RAML-to-JAX-RS module and generated some JAX-RS output with it. In the past I’ve worked with SDKs that provided POJO classes that allowed me to construct the request body in code, rather than piecing together an XML or JSON string from dynamic bits building up a final String body to send. Likewise, the SDKs converted responses into POJO objects that made it easy with code to deal with the responses, rather than having to parse xml or json directly. The current RAML-JAX-RS does not generate POJOs from any of the listed schemas in the RAML file. I am therefore starting a project using the RAML-to-Java module, to then get the list of all schemas and “attempt” to generate POJOs from those schemas. Presently I am looking to use the XJC classes in my code if an XSD is listed, and if the schema is json, I am looking to possibly use the jsonschema2pojo.org to try to convert json schema to pojos. I wanted to reach out before I got too involved to make sure another effort isn’t under way already and/or if this is something that would be useful to others. I do understand that some API developers may resort to using something like https://apimatic.io/ which supports RAML files, to generate client SDKs for different languages. However I still find that this is not as useful to me as generating POJOs from our schemas and providing an SDK with the POJOs being used. I also feel that generating POJOs and using them both client side and server side validates the schemas are correct. It also sets up the ability to use the POJOs in generated test automation code as well.

Anyway, wanted to see what others things, if this is something others need or would want, any arguments against it (and why)?


#2

Generation of POJOs based on JSON Schemas has been available with RAML-to-JAX-RS since day one (it’s built with jsonschema2pojo, BTW).

What’s not supported is XML Schema to POJOs. It would indeed be a nice contribution to https://github.com/mulesoft/raml-for-jax-rs/tree/master/raml-to-jaxrs :wink:


#3

Really? I might be missing something then… I ran the tool and I didn’t see any POJOs created that I know of… I assume my definition might be different though. I expect individual simple POJO classes to be created, such that I could JAR them up and distribute them to be used in an SDK, test automation code, etc. To be fair, I only tested a very simple RAML doc with one resource and one json schema object. Does it embed the POJOs into the generated JAX-RS classes? If so, that won’t help “share” the POJO’s with other code such as SDKs.

As for XML Schema… I can probably add that… I started on my own JAX-RS generator primarily because I didn’t like the use of the ResponseWrapper as a return type. I want to have the json/xsd schemas turned into pojos and used as the actual method response types and request types in the generated resource methods. I started adding the code to convert XSD to POJOs. Also, I am using the modified API Designer that another fella modified to work with mongodb, as we’re sharing documents with a team and that worked well. So my code will need to be able to properly figure out where all the paths to json/xsds are at… in my case its on a mongodb server port 10000, as opposed to the default API Designer using the HTML 5 storage paths.


#4

The location of the generated classes depend on your configuration but here is what it is for the provided Jersey example:

jersey-example/target/generated-sources/raml-jaxrs/
└── org
    └── raml
        └── jaxrs
            └── example
                ├── model
                │   ├── Presentation.java
                │   ├── Presentations.java
                │   ├── Product.java
                │   └── Products.java
                ├── resource
                │   ├── Presentations.java
                │   └── Products.java
                └── support
                    ├── PATCH.java
                    └── ResponseWrapper.java

As you can see, the POJOs are in the “model” sub-package.

Regarding the ResponseWrapper: how can you specify the response code if you return the POJO as the method response? Moreover, how do you enforce that developers only respond valid codes if you don’t guide them with something like the ResponseWrapper?


#5

You are correct with the Response issue… I was looking at the generated code and I think partly it’s due to not having yet tried to take it past the generated code to see how it works when deployed. When I last wrote JAX-RS APIs (not too long ago) I actually returned the Response object for everything, and typically did something like return Response.entity(pojo).ok().build() or in the case of an error I would return Response.status(errorCode).entity(errorPojo).build(). So the code I see generated when I glanced at it looked a little different than what I was used to. Not necessarily a bad thing, and you are right… returning the POJO alone makes it impossible without a response filter to handle error response bodies, and different statuses. I’ll definitely deep dive more on this before I look to change things.

For some reason, I don’t recall seeing a model/ directory or resource…but like I said I briefly glanced at it, so it’s more than likely my own fault for not looking in more details at it.

If possible, I’d like to add the XJC option (in code, not calling to XJC) to work with XSDs. What I am unclear with at this time is in the case where I am using the modified designer to store files in mongo… if the current RAML to JAX-RS would work with that… or would needed to be further modified to support paths outside of the HTML5 storage paths?


#6

Unfortunately, I don’t know enough of the Designer to answer your last question. Hopefully, someone else will chime in.

Otherwise: great ideas bounced back and forth, thanks for this dicussion.