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.