Dan Jemiolo posted today about his restdoc tool,which produces Gregorio Tablesfrom comments in REST service implementations designed to be runin Project Zero.He also posted to the Project Zero forum, and included some screen shots of the output of his tool, here.
Here is what's cool about this:
I love it when I can keep artifact information like this with my source code;easy to keep in sync.
It's genuinely useful information.
I'm tired of the "we don't need no stinkin' tools" attitude of some of the RESTafarians. Baloney. I think we cancertainly live without overengineered tools like WSDL,but having small tools can certainly help.
Now, for some rocks:
As I mentioned in a comment on Dan's blog, it would probably be useful to have this information available at runtime on the server; the server couldactually validate what it's doing. And I'm not talking about the serverreading it's restdoc information back in; I'm talking about the serverhaving that information available to it, at runtime, obtainedreflectively.The advantage is that you know the information is never stale. No more,"When was the last time I ran restdoc again?".In Java, you would presumably use annotations to do this.
While Joe's tables included a non-precise description of the HTTP content for themethod / uri rows (eg, "Employee Format"), restdoc only includesthe 'format' (eg, JSON). I'd prefer to see more precise typing,but to start with, something as vague as Joe's would be good.
That HTML table looks like it may be too wide to be viewed on an iPhone. The good news is, I don't have to worry about that problem.
Finally, not to knock Dan at all, but I really have to wonder what'sgoing on if the best we can do is describe our services in human readable tables of text. Really? I mean, can't these multi-core,multi-gigahertz computers of ours really help out anymore thanby rendering some HTML to a display that we read while hand-coding our HTTP invocations?
That just isn't right.