enunciate

Given an abstract, generic Resource class and a concrete implementation: public abstract class AbstractResource<T> { @Autowired private SomeService<T> service; @Path("/{id}") @GET public T get(@PathParam("id") String id) { return service.get(id); } } @Path("/people") public class PersonResource extends AbstractResource<Person> { } It appears that when generating the docs for PersonResource , Enunciate is not picking up the fact that get() returns a Person . Person is not listed in the Data Model > Data Types section. Under the GET section, Response Body shows the element type as "(custom)".

How do you document a REST API? Not just the documentation of what the resources are, but really what is the data that gets sent in the request and what the data is that gets sent back in the response. It is not useful enough to know that something expects XML to be sent and returns XML; or JASN; or whatever. How do you document the data that gets sent in the request and the data sent back in the response? Best I could find so far is the Enunciate tool where you can document your REST API and the data elements. Is Enunciate the right type of tool for this and am I missing out on any other

If I have a REST based service written in the Symfony [symfony-project.org] framework (i.e. PHP), is there any decent tools/frameworks out there that will parse my code and generate API documentation? The Java based framework enunciate has documentation capabilities similar to what I need, you can view an example of this here: http://enunciate.codehaus.org/wannabecool/step1/index.html . I understand the premise of REST based services are supposed to be self evident, however I was after something that would generate this documentation for me without the need to manually write up all my