Client Generation Re-Loaded: Support in RAML for JAX-RS?


#1

I know, there has been a recent topic on Client Generation, but that one didn’t cover RAML for JAX-RS at all. So what’s the situation there, specifically?

I recently cloned the master branch, and noticed that a ClientGenerator.java has recently been introduced there. It seems that this is still work in progress – even when I activated that Generator (through CLI or Maven plugin) I didn’t get any meaningful Java code for clients. Or did I do something wrong?

What I was hoping to find was this:

  • Having type-safe DTOs generatad (this is same as for server, and works already).
  • Having a fully implemented client class that provides Java methods for all of the resources and operations of the API.
  • Or, some kind of builder class that makes it easy to build JAX-RS requests based on the API.

Is this the direction that the new developments are heading to? Or is the ClientGenerator.java about something different? Is there any kind of road-map for these developments? Is there a sketch/example of what generated client code would look like?

Sorry for hassling you with all these questions. It’s just that my team is in dire need to provide Java-clients for our RAML APIs. We were hoping to re-use existing frameworks for that purpose, and currently RAML for JAX-RS is our best shot. Thus some alignment regarding ongoing developments (and possible contributions from our side) will be much appreciated.


#2

Good questions. I am actually trying to build a Java SDK from RAML using JavaPoet to build the SDK. I am having various issues though using the Java RAML parser object… specifically the main issue is figuring out if each Mimetype schema refers to an included schema earlier in the RAML file, or if it’s a body of schema at that specific point in the RAML file. More so, either way, I am unclear how to determine the POJO generated files (from json schema that I am doing) to use in the response type and request parameters. For example, I have a /resource endpoint with a GET method type, and a MimeType application/json. I have that linked to a json schema file that I !include in the schemas: at the top of the RAML file. I actually first get the list of schemas (and their file locations), and then run jsonschema2pojo (java library) on the json schema files, to generate java pojo objects. These are in my sdk/…/model folder. I now want my getResource() to return the generated Pojo java class type. However, I am not clear on how to figure out the jsonschema2pojo generated name for the schema that is used by the /resource GET endpoint. Worse… if the schema is included right there in the /resource section, instead of a separate !include file, I am not sure how to figure out the name either. At least not yet.

Anyway, the codegen project is intended to use Handlebar.js templates to generate SDKs in different languages, and likewise could be used to generate JAX-RS and other server side bits. But there is still several unanswered questions, such as the issue I am running in to… how to find the generated schema pojos, and to figure out the right pojos to use in the request/responses.


#3

Regarding your Java SDK from RAML:

Colleagues of mine already did some exploratory work into the same direction, and they faced much the same problems. However, not all of these seem to be limited to the client side. Thus I was hoping to find synergies with existing service resource generators from RAML to JAX-RS.

Regarding the codegen project:

Are you refering to the RAML Client Generator? That one seems to use Handlebar.js, too. We were considering to use it, or, a similar JavaScript-based solution. However, it seems the gap between what’s there out-of-the-box and a nicely working Java client generator is as big as for RAML to JAX-RS. And to me it seems easier to generate nice Java-code from Java itself (like RAML to JAX-RS does it), rather than using a general purpose template language.

But we’ll investigate further…


#4

@michael Yes I was referring to the RAML client generator. We’ve had some discussion around this on the forum and I like the idea of it. However I am on a time crunch to have something working and I don’t quite know JS well enough to utilize the template system to build a java language (or any language) generator. I get the gist of it, just not sure how in JS code I can find the generated java pojos from json/xsd schemas, and figure out the names of those, and then use those names in the method response types or request types and parameters.

I’d love to see the handlebars.js system work… it could allow for “one templating engine to rule them all”. You could theoretically build client and server side, documentation and more from this one engine. Until there is a lot more documentation, examples, even a complete language addition for java, ruby, etc available, I think you and others are correct in that using a java tool to build java code is going to be the better solution (at least for java).

I am all for whatever the community wants to drive forward… after all I think we all benefit if we can utilize supported community driven projects. How nice would it be if RAML already had client SDK generators working to put out java, .net, ruby, python, go, etc? Hopefully the 1.0 spec gets finalized soon…been 6+ months since it was supposedly going to get finalized, so hoping it, along with various tools (e.g. RAML java parser and JS parser) are updated quickly so we can move to it sooner than later.


#5

Just FYI, we decided to go with our own, Java-based implementation for Java-client-generation. We’ll not reuse code from RAML for JAX-RS, but we’ll make use of much the same libraries and principles. We’ll also think about releasing our solution as open-source eventually. But that may take some time, and is not fully up to myself.

Still wondering though: the ClientGenerator class in RAML to JAX-RS core, where is that heading?


#6

@michael

I was looking at the ClientGenerator as well. Not sure myself, but it seems to me all of these client generators, code generators could be put in to one big code generation project rather than separate projects. That is the overarching goal of the raml-client-generator project, although it’s title makes it out to be client only.

I’d be interested in collaborating with you if your allowed and up for it with regards to Java RAML SDK generation. Shoot me a PM with contact info if you are.


#7

Just a quick follow-up on my post from 4 month ago.

We have done some work on a Java-based client-generator for Java as envisioned back then. (The preliminary project name is Rammler, the German word for a male rabbit.) Progress was good in the beginning, and we came up with something that is suitable for internal use.

However it still lacks several important features, most notably support for type-safe DTOs. And unfortunately, we had to move our focus elsewhere. So we did not have the chance yet to get it to a publishable state yet. Still hope that we’ll eventually open-source it, in which case I’ll announce it here…


#8

@michael - sounds good - let me know if we can do something!