How to document a Symfony based REST API (similar

问题:

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 endpoints, supported formats, sample output etc.

Thanks

回答1:

Not sure if you've seen Swagger before. They seem to have a PHP compatible version, though I can't really vouch for it personally. It does some automatic API documentation generation comparable to enunciate, though it does look like it requires some heavy manual documentation via PHP comments. That being said, I think the manual effort will be the same or less than making your own via wiki pages, and the output is much, much nicer.

Just as a factoid, it looks like Enunciate has indefinite plans to eventually support other platforms, but the relevant Jira ticket is currently Open waiting for a sponsor to take on the work.

From the ENUNCIATE-356 Jira ticket:

The first step to supporting other languages is to decouple the Enunciate model from the Java model. This work is being tracked and logged at ENUNCIATE-584. Unfortunately, it never made it out of the investigate phase because of how heavy it is. Unless a sponsor for the work is found, I don't anticipate taking that heavy load on anytime soon.

Edit:
Found a similar question where someone mentions a GitHub project dedicated to Swagger+Symfony2. This other question is the same, but no additional information.

回答2:

To my knowledge there is no way to automate the documentation of media types.

If you are using a media type like XHTML then a web crawler like Google sitemap may produce some useful output to show the relations between your resources.