2

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

Guy Gavriely
  • 11,228
  • 6
  • 27
  • 42

1 Answers1

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)

Community
  • 1
  • 1
LiorH
  • 18,524
  • 17
  • 70
  • 98
  • Thanks, for an automatic human readable client documentation I've dug a little and found http://enunciate.codehaus.org/ for Java, I wonder if there is an equivalent tool for grails – Guy Gavriely Dec 06 '09 at 14:39
  • Check out the following getting started http://enunciate.codehaus.org/getting_started.html and the example http://enunciate.codehaus.org/wannabecool/step1/index.html – Guy Gavriely Dec 06 '09 at 14:50
  • your link to twitter documentation is broken. can you update? – Randyaa Aug 08 '14 at 20:18