Grails REST XML API definition

Question

Striving to ship a well documented application, I'm looking for a good way to describe a REST API for my Grails Application users.

I know that REST calls should be simple enough to be described by examples, but it doesn't feel formal enough.

I've spent a couple of hours looking for a solution suggested by other Grails users, but didn't find a neat solution besides a recommendation to use WADL or WSDL 2.0

This looks like a good direction, but there must be a simple way to do it in Grails.

I'd appreciate some guidance for a process to generate a REST API based on my model objects preferably with the ability to filter or control the exposed fields, plus, a nice graphical way to present it (something like the XSD Eclipse plugin)

Thanks! Guy

Answer 1

I would suggest to avoid WADL or WSDL for API documentation, you can see this question where I explained my reasons: Why the slow WADL uptake.

WADL or WSDL are usually used for automatic client code generation, they are not human readable documentation. I don't think WADL or WSDL are very useful for a user to figure out how to consume the resources correctly.

I prefer the good old html documentation, for example I like the way twitter documented their API

If you insist on automatic generation of resources documentation I can recommend on the ATOM service document. Many REST framework can generate it automatically based on the resources annotations. (e.g. Apache Wink)