Best Practice for documenting Symfony2 based REST API

Question

I like to document my API (REST with JSON) which is written in PHP with the Symfony2 Project. This means I would like to write a public API, which I can give out to my clients, without showing them my internal functions etc.

What is the best practice to write Documentation in the public functions (Controllers, etc...). I'm currently using YAML for routing, which seems to be incompatible with the Annotation Based PHPDoc.

Thank you in advance!

Answer 1

You should then use NelmioApiDocBundle which was designed specifically for the need of documenting Restful Symfony2 API(s).

Find the bundle's documentation here .

It provides an ApiDoc() Annotation for Controllers,

• The ApiDoc() Annotation .

And it also allows you to browse the whole documentation through an interfactive web interface,

• On-The-Fly Documentation - Web Interface .