Building RAML to JAX-RS


#1

Hi,

I am having some difficulty in understanding what steps to take to use the RAML -> JAX-RS parser to build JAX-RS from my RAML.

The first thing is… where do I find my saved RAML file? I am running the designer locally, and I see my saved documents in the designer, but can’t find the .raml files. Is there an export feature… for that matter how do I open an existing RAML file? Seems copy/paste is the only way?

Assuming I can find my .raml file, being a complete maven noob, I am unclear how I actually run the generator and specify my RAML file, as well as things like base package name, src directory to generate code into, etc? Can anyone lay down the quick guide here, maybe with an example or two of the actual command line I’d use to run the parser on my RAML file?

Thank you.


#2

Alright, I sorta figured it out. It’s not clear on the initial README.MD, but in the new combined project, going in to the raml-jaxrs/core folder, there is a command-line.md file, that explains things. I think this could be improved upon to highlight in the main README.MD how to actually build and run the tool so that people can quickly create java source from raml. I am a little confused though, the info says it creates interfaces from RAML, but mine created a concrete class. I liked the idea of interfaces so that I can extend/implement them and if my API changes, my code would not compile which I would then fix to match the changes. Is this not the case?


#3

The first thing is… where do I find my saved RAML file? I am running the designer locally, and I see my saved documents in the designer, but can’t find the .raml files. Is there an export feature… for that matter how do I open an existing RAML file? Seems copy/paste is the only way?

The official API Designer only supports Local Storage, a HTML5 feature where you can use the wrowsers cache as a sort of files system or keyvalue storage. This means that whenever you open your browser and head to the url of your designer (localhost:3000 I guess) all the objects should be inside your browsers cache… If you use the developer toos for chrome or firefox you should be able to explore the LocalStorage and find your files there. This is of course not very usefull if you have multi-file RAML specifications (like my usecase).

We are using RAML to stablish a standard interface (40X, 50X, queryParams, security…) for all the APIs deployed on our platform, this means we generate traits, JSON schemas, and response examples that all the developers of new API’s should include (i.e. the 404 json should be the same on all APIs), because of this and since we wanted to have a team working on several RAML spec files (multile RAML files, edited by multiple users via Web), but also serve the RAML files via a REST API to generate documentation and code gen, we modified the Designer to meet our requirements. Check
https://github.com/brianmc/raml-store and https://github.com/hadesbox/raml-api-designer-store. These web applications can be deployed on a web server and they store all the info on a MongoDB, so you can easly exploit it from outside if you require so. I recommend you take a look at this tools if you plan to easly share or have a team working on several files at the same time.

You can of course use Mulesoft Api Designer http://api-portal.anypoint.mulesoft.com/raml/api-designer, that would give you a public url for your files.


#4

Hi,

Thank you for the info. Very interesting. We’re looking to use RAML (and Postman) to have a single source of truth document that can be used to generate SDK, unit test, server side (JAX-RS), and documentation from. It seems that some of the projects, like the Jax-rs module, and the raml2html are “close” to what we want. I am working on adding a code generator to generate SDK code for Java and Python that would utilize the Raml-to-JaxRS models created from JSON/XML schemas declared in the raml file. However, thus far, the jax-rs output seems to obscure the models within the jax-rs interfaces themselves, rather than generate POJO model classes that could be bundled and shared with SDK code. So I will probably look to build my own JAX-RS generator that ties in the Models with both the JAX-RS server side, the SDK client side and unit test/automation test output as well. The Raml2Html looks nice, but we’d want a few more defining features, probably specific to our internal use.

Overall I am quite impressed… I like that I can use the Java Parser module to get a Raml object and from that I think, with some understanding of traits, types, etc I should be able to build SDK/test generators and possibly a java based raml to html 5 generator. I actually want to look at using ReactJS with HTML5/CSS3 and something like Bootstrap for the final documentation output.

We may look at the Sublime plugin to use for editing the RAML file, maybe that will improve if necessary with better features than the API Designer itself has?


#5

Checkout Abao for unit test/automation it looks promising.

RAML2HTML is very nice we are using it to generate static and clean API docs for our internal usage.

Sublime its a great way to go also if you combine it with control version tools like Git.

Codegen is always a complex problem, not because its difficult to generate the code but because different developers and companies always have houserules on how to implement a project (patterns?) or what frameworks/libraries you can use (spring, flask, struts, jax-rs, express, hapi, strongloop)… and thats without even starting to talk about programming languages (python, php, go, ruby, node). JAX-RS is the standard for Java, but I don’t see it been used a lot… again sometimes your company or boss forces you to use a specific framework so you will have to make your own codegen tool.


#6

I completely forgot to mention… but I proposed to the guys in http://apimatic.io/ to add RAML… and been contributing with them for the last weeks, and NOW you can generate working SDKs in a wide list of programming languages with their service, their SDKs use UNIREST. A very interesting library to create light weight REST clients by Mashape.

Check how this API is docummented with clean simple unirest calls (rather than a SDK).

Our findings is that Its more convenient for developers that are integrating your API to use Unirest example calls in 8 languages (cocoa, node, python, java, .net) than supporting a big fat monolithic SDK.

Of course if your API is super complex (aka. AWS SDK… where you have a client object, which you inject a request object, and then you read a response object) then a big fat SDK is the only way to go.


#7

Thanks again, good info and pointers. Will check into them.