JAX-RS => RAML tools?

#1

Hi,

Are there any tools for generating RAML output from JAX-RS annotations? I’m the author of wsdoc, which groks Spring-MVC and / or JAX-RS annotations and JavaDoc and generates (pretty ugly) endpoint documentation; I’m wondering if it’d be worthwhile to add an option to output RAML instead, or if this is already a solved problem.

Thanks,

-Patrick

#2

Hi Patrick,

I think that’s very relevant. There’s been initial work on RAML --> JAX-RS scaffolding and discussion of JAX-RS --> RAML spec generation. @comptly and @ddossot and @rezaloo might comment more here … and there’s another thread on JAX-RS too.

#3

@pci: this is still a problem to solve and would be a great addition :smiley:

#4

Well, at least the RAML --> JAX-RS direction is now an ongoing project (commissioned by MuleSoft) you can already start using, though JAX-RS --> RAML is still waiting…

@ddossot’s slick new RAML --> JAX-RS codegen project is now listed on the projects page and is available on github. It’s very early, but quite useful already. Feedback is always appreciated.

#5

Any news about this feature (jax-rs to raml) ?

This features would be excellent for communities :smile:

Thanks

#6

Im working on scaffolding tool that generates a spring-mvc spring-security hibernate java project… its almost finished, I may be able to share it when its working :).

The tool I’m creating is built from scratch, no JAX-RS… in node.js… it uses the raml module for node to parse the Raml Files, and swig for templating…

the second phase (if any) would be to create a yeoman Java generator for raml.

#7

This is an interesting idea.

Unfortunately in many applications, the jax-rs annotations are used simply to mark methods that handle specific paths, and nothing more: @GET @Path(value = pets/{petId}).
This means that we are unable to add descriptions, and other notes that make RAML so readable. Additionally it is not uncommon to see jax-rs annotations stratified across multiple layers of code, making it hard to generate a concise spec from this.

Generating RAML from java annotations however, seems to be a very viable approach. We can see that swagger has this already: swagger java annotations

I propose designing a set of java annotations specifically for RAML, and a building processor for those annotations

I understand that this breaks the idea that RAML should generate the code, but at the enterprise level we are forced to generate spec from code to examine the current state of our build.

I would be willing to write the processor for this, but I would like help designing the most concise set of annotations possible to make RAML the best it can be.

If this effort already exists, let me know where I can find it. I am new to the community here.

Best,
Scott

#8

Hi Scott…

in this regard the RAML->Java is my winning horse rather than the Java->RAML scaffolding (I may be completely wrong…).

My arguments are:

  • Having an Java->RAML approach is more extensible… this means if we design and create a core functionality for scaffolding, and a plugable processor to generate Java but another user want to generate Node.js or Ruby or .NET it would be easier for anyone to write a processor for their own language.
  • To focus the scope of the scaffolding tools, I would suggest that rather taking specific language REST implementations (like the java only JAX-RS), we should go practical and if we can agree that the MVC is the most widespread web programming model, then all RAML scaffolding tools should focus on that… which is just generating the CONTROLLER layer of the applications regardless the language (PHP->Zend, Node->express, Java->SpringMVC, etc…).

again just my arguments which are completely open to discuss :).

#9

FYI, the approach we are taking with wsdoc integration pulls docs from java doc, and adds a single annotation to designate the planned root of the API, which is configured at deploy time and so is unavailable.

What other pieces of data are you concerned about?

#10

Sorry for the delay on responses.

After chatting with fellow employees, we have decided to build a tool that is coincidentally much more inline with this thread’s topic.

The tool, in the form of a Maven plugin, will take two inputs at configuration, the RAML specification, and the file path of the JAX-RS annotated resource layer. At build time, the tool will compare the implemented service layer with the RAML specification to ensure all Paths, Actions(GET, POST, PUT, ect…), and QueryParameters are implemented as described in the RAML.

So although it doesn’t directly generate RAML from JAX-RS, it does let you know exactly where your resource layer deviates from the RAML. This approach sticks with the design first mentality, while allowing the customization of the resource layer so common in enterprise development.

The tool is currently functional and will be released to the public by us once it has been internally code reviewed.

Why did we chose to limit it to JAX-RS annotations?

  • Had to convince the boss it was worth company time.

Why don’t we just generate the resource layer?

  • We use iterative Agile development, and regenerating a resource layer for each new spec, copy and pasting the old implementations would be worse than just writing the few lines that we need.

What can the tool do now?

  • Function as a maven plugin
  • Read & validate raml from file
  • Read JAX-RS annotated resource layer, and build a java represented RAML of the resource layer
  • Compare Resources, Actions, and QueryParameters to look for both missing items and extras not specified in the RAML
  • Print any discrepancies in an easy to understand way at buildtime
  • Fail the maven build if discrepancies are found
  • Ignore any extra methods in resource annotated with @ExcludedFromRaml
  • Ignore any non-JAX-RS annotated methods

What it needs:

  • A much better name! Internally we call it the Raml Contract Validator
  • Ability to ‘flatten’ RAML specifications to allow for proper trait and resource analysis
  • Ability to look at multiple resource classes (internally we don’t use that feature of JAX-RS, but it’s commonly used)
  • A real testing suite

Any suggestions, ideas, or reactions are welcome.

Best,
Scott

#11

Adding to this thread, a tool we have released this week:

It’s a first release but it has some cools features that could be interesting for you.
I’d love to see you opening issues suggesting more features.

Best Regards.

#12

@nohorbee Your jaxrs-to-raml project seems to be much more robust than what we have thrown together inside our validator. We will look to swap over to using yours internally before releasing the validator.

#13

Thanks @Scott, and please, let me know if we can help you in any other way!

Cheers!

#14

So now we have both JAX-RS to RAML and RAML to JAX-RS in the projects page, let the fun begin…

#15

All,

Sorry for the delay.

Here is a link to the RAML contract validator as promised: Raml Contract Validator

Feel free to play with it and send in pull requests!

#16

Hey @Scott,
I’ve just seen this, and it looks promising.
I’ll be playing with it these days.

Regarding to your last section on the MD:

  • Transition to use the mulesoft RAML parser, instead of the current custom built one: I would say, GO FOR IT

  • Auto-generation of swagger docs, for those still stuck on swagger: Isn’t out there any tool already doing this?

  • Incorporation of auto-generating raml html documentation: Strong suggestion: Check these projects: https://github.com/kevinrenskers/raml2html (the original one) | and https://github.com/zestia/grunt-contrib-raml2html (let’s you include the previous one as a grunt task, for an automated process)

  • In resource class linking of html documentation: I’m not sure I’m getting this one. Do you want to explain this further?

I will be contacting you soon. I think this project needs to be in the RAML website projects list.
Cheers!

#17

Was trying out the jax-rs to RAML. It came up with an error that the target java of 1.7 was invalid. When will there be a version available for 1.7

#18

I strongly recommend you to use RAML for JAX-RS. It’s actually a merge between the old jax-rs to RAML and RAML JAX-RS Codegen. And since it’s all there, we are just maintaining the first one these days.

#19

Hi all,

Just discovering this RAML tool and it looks very slick. I especially like that Postman, the most widely used Rest API Client tool is working on adding support to import RAML (and export I believe) in the near future.

We’ve been after a “holy grail” solution where by we keep a single source of truth document that can then be used to generate SDK, Documentation, server side code, and we simply modify the source of truth document and regenerate. First question… can the RAML -> JAX-RS basically do this for us? We’re possibly using Spring but may go JAX-RS.

The more important question is… if we generate JAX-RS, then add code to handle the resources… then say we make a mistake… we want a GET not a PUT (yah…that would be pretty bad mistake ;). When we change the RAML doc, then regenerate… does it diff or merge the JAX-RS generated stubs with our existing .java source where we added code now? Or does it blow it away? I have yet to see this work, so not entirely sure how that is handled so that we can maintain/update/change/fix the source file such that we don’t blow away our added code. My guess is the RAML -> JAX-RS must generate interfaces that our code would then extend from or implement, rather than actually generating concrete classes with “stub” methods that we then insert code into?

How accurate/good is the generated JAX-RS code? We want to support JAX-RS 2, possibly using Jersey 2.6 or Spring (not sure yet).

Also, what about client side SDKs… can that be achieved at this point? We’re wanting to add java, python, .NET and Ruby SDKs and ideally want them generated from the same single source document that generates the server side and documentation.

Thanks.

#20

then regenerate… does it diff or merge the JAX-RS generated stubs with our existing .java source where we added code now?

No it is not supported currently,

My guess is the RAML -> JAX-RS must generate interfaces that our code would then extend from or implement, rather >than actually generating concrete classes with “stub” methods that we then insert code into?

Yes, you may stick to using interfaces.

How accurate/good is the generated JAX-RS code? We want to support JAX-RS 2, possibly using Jersey 2.6

It works in tested usecase and I am willing to fix issues ASAP.

Also, what about client side SDKs… can that be achieved at this point? We’re wanting to add java, python, .NET and Ruby SDKs and ideally want them generated from the same single source document that generates the server side and documentation.

We are able to generate Java client proxy but it is new feature.

We’re wanting to add java, python, .NET and Ruby SDKs and ideally want them generated from the same single >source document that generates the server side and documentation.

Other languaes are not ready yet and we think about them as a thing that is our of this project scope. I will try to talk with guys here about it.

Regards,
Pavel