Auto documenting REST API in PHP

Question

phpDocumentor seems to be the standard for documenting PHP code, though I have to wonder why it hasn\'t been updated in years..?

However, it does not seem suitable f

Answer 1

The easiest thing to do is use a docblock tokenizer / parser. There are a couple of them out there (I'll plug mine shortly), but basically they can examine the docblock and tokenize any custom (or non-custom) docblock tags. I've use this inside a framework of mine to define view helper types via a tag called "@helperType".

Like I said, there are plenty out there, but here's mine to get you started: https://github.com/masterexploder/DocumentingReflectionMethod

Basically, use something like that and you can use it to both generate your docs, and to do stuff like auto filtering, validation, etc.

As far as unit test creation, PHPUnit can generate those automatically from your classes (check their docs for more info: http://www.phpunit.de/manual/3.5/en/skeleton-generator.html#skeleton-generator.test

You can also have phpdocumenter parse your custom tags: http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.customtags

Finally, there is one framework out there (that I know of, I'm sure there are tons) that uses annotations to do all sorts of restful goodness (perhaps saving yourself some work): https://github.com/recess/recess

Hope that helps!