Richard Boulton @rboulton http://lemurconsulting.com/
Richard develops Xapian while working for Lemur Consulting.
Recently he was working on a project involving several web APIs interfacing with each other and he wanted to have a good way of seeing what each API was doing. One way would be to ask all the developers to create and maintain documentation, but with rapid development, this would quickly get out of date.
Richard started from the idea of having comments by the code (like Javadoc or rdoc) but has taken it further to make the documentation machine readable. In the case of web APIs, this gives the benefit of being able to create live documentation — some simple comments together with a form that allows you to try out the API directly.
At the moment, the framework he has made (WSGIWAPI) is not quite complete (he put it together on train journeys to and from work…) but it is already being used in the Flax project — an indexing and search server based on Xapian.
WSGIWAPI is works in python and uses python decorators (similar to Java annotations) to produce a WSGI object with documentation included. A WSGI object is a python web service plugin (see http://wsgi.org/wsgi/Learn_WSGI for details) that can be added directly to a web server — so by adding documentation to each method and a couple of lines of plumbing to a class, you can generate full web services complete with documentation and examples.
Since the documentation is machine readable, it would also be possible to generate a Javascript client library or a WSDL specification automatically from the code.
Nice idea — though I think it would get further traction if the idea was rolled into an existing framework rather than being on its own. There’s nothing stopping that happening — the WSGIWAPI code is freely available from http://wsgiwapi.tartarus.org (code on Google code at http://code.google.com/p/wsgiwapi/).
No comments:
Post a Comment