Take a look at RAML

[feniix]

https://www.youtube.com/watch?v=5o_nExedezw

http://raml.org/projects.html

[paulovictorv]

@jknack

Went ahead and did a little bit of research on the subject.
The main use-case I first saw for using RAML was to auto generate documentation, but now I see that it's possible to define the whole API using only the language.

RAML 1.0 will support adding custom metadata to the methods description, which will allow it to map the specific HTTP route with a Java method. This will be very powerful, meaning that it'll be possible to auto generate consumer-facing documentation as well as defining route bindings in one go.

Also, there are a bunch of auto-testing tools that can run unit tests on a mock server (that Jooby can create based on the schema) and a full integration test.

Imagine delivering a framework that (in theory) is capable of running unit/e2e route testing out of box... Oh my..

[feniix]

@paulovictorv very cool!

[jknack]

Did you seehttp://jooby.org/doc/swagger/?

Think is better and give you the same features!

[paulovictorv]

Yeah, I think they have the same philosophy,but I was thinking the other way around.

Let the user instead of defining routes straight on code (which is nice), define them on the RAML file, together with the method binding. Defining routes on a same place, but still separated from the actual application code is really nice, and having that definition together with the documentation is just the cherry on the cake.

Now, imagine hooking up on mvn test phase, running one of the many server validation tools using the RAML file as the guideline. You kill two birds with one stone: generate docs and test it .

I've lost count on man-hours "wasted" creating essentially repeated test classes: one for the web api layer, another for the actual application layer.

About defining routes separate from code, I've had experience with JAX-RS, express and Play! Framework style of route definition. They all shine, but I've seen that for large api's, defining it separated from code (like Play does) makes it easier to organize. The thing that is really bad with Play style is that it's too plain. It's hard to organize routes in a readable form, which is not even needed for RAML since we can generate an UI for the developer to navigate (which swagger already does).

What you must consider is that, if this feature is introduced, will it violates Jooby's philosophy? My opinion is that it doesn't. Jooby should be simple for simple apps, but sophisticated for larger ones.

But I ramble :)

[jknack]

@paulovictorv do you have experience with RAML?

Next release will have a spec module that basically does all the hard work... all we have to do is to transform the output of the ``spec` module into RAML.

Are you able to work on this?

[jknack]

@paulovictorv can you help here?

Thanks

[paulovictorv]

Hello, sorry for the delay.

I'll try to work on this in the next few weeks. If I have any questions I'll let you know.

[jknack]

I did it: #275

it works pretty well