Hi! I've created a public restful application and I would like to generate API documentation for users. For REST i think I have to provide URLs and parameters.
What is the best way to prepare it? Thanks!
+1
A:
The most important thing to document is your media types. So if you are using a custom XML vocabulary, you should have an XML schema somewhere to describe it. The beauty of using "hypermedia as the engine of application state" is that so long as the client understands the media type, the URLs should be discoverable from the entry URL of the service.
However if you want to provide more information, RESTful Web Services recommends using WADL to documents RESTful application. The book describes WADL as "an XML vocabulary for expressing the behaviour of HTTP resources". It allows you to specify URIs, media types, HTTP verbs etc.
Also, because it's a standard, there are already libraries and tools out there that can generate stubs and HTMl docuentation from a WADL document.
ctford
2009-09-22 17:12:36
+1
A:
You could use the Api Generator plugin for CakePHP (which is used to generate the production CakePHP API documentation)
inkedmn
2009-09-22 17:33:58