Jaxrs-raml generator Issues


#1

Hi,

I am new to RAML and I just started using the jaxrs-raml-maven-plugin for generating raml from my java based jax-rs rest API.
The project has just begun, so I was of the opinion that I should start off the documentation and design sooner rather than later.
I was able to generate the raml from my code, however I did observe a few issues with it:

  1. The raml generated is 0.8 and not 1.0, Is there a plan to release mvn plugin to do that?
  2. When using @Path("/{version : v[0-9\.]+}/resource"), the generated raml gives me /{version}/orders but when inspected it complains Invalid resource name : unmatched ‘}’
  3. When using @Path("/{version : v[0-9\.]+}/resource/{id}/subresource/{sid}"), the raml just doesnt get it and generates /}/payments/}: , with the same complaint Invalid resource name : unmatched ‘}’.
  4. Also, is there a way to support @Consumes and @Produces annotations which define custom Media Types like application/vnd.org.app_v1+json ?

What I am using:
jaxrs-raml-maven-plugin v1.3.4


#2

You said the project just started… so it may not be too late to offer an alternative method of using RAML for not just documentation, but as your single source of truth. Rather than using JAX-RS to RAML, spin it around, use RAML to define the API first, with JSON Schema for the models (that turn in to Java POJOs and can be used as DTOs and backing models to entity beans). In this way, your front end API, documentation, even testing and mocking capabilities are all automated from your RAML API first design.

RAML 1.0 would be ideal, but I am not sure of the state of things with RAML 1.0 to JAXRS (or vice versa if you are stuck on going it that way). RAML 0.8 is well enough for most API scenarios, however, and the JAX-RS 2.x generated works quite well.

I could give a number of reasons why this path is better, but mostly they are my own experience and opinion. However, if you are building an application that is going to have an API, then the API becomes your contract to anyone consuming it. You can build SDKs from the RAML and JSON Schema files as well for many languages, but mostly, for me it is about using a single source of truth to build everything else from. From the API endpoint implementation, to the documentation, to testing and more. Postman, probably the best API testing product available, imports RAML as well, to some degree and with a bit more work, it is not difficult to quickly turn a RAML defined set of API endpoints in to a 1 to 1 API testing collection in Postman, that can then be used to quickly assemble tutorials and end to end API tests scenarios. All of which can be run using Newman with nightly builds (we do this now by spinning up our entire environment with docker containers and then running the automated Postman tests with Newman against the APIs).

Anyway, I have done projects both ways, and frankly trying to keep code in sync, with javadoc, and tests, etc… is much more difficult than starting from RAML (and JSON Schema) with documentation in the RAML files, than the way you are currently going about it.