REST Service documentation with PHPDocumentor
I’ve just been hacking around with PHPDocumentor getting it to automatically create the documentation for the Cohere API and seems to be working well.
I have apilib.php which contains the PHP calls to the functions, then service.php is a wrapper around the apilib.php and provides the actual REST based services. Service.php is basically just a big switch statement, so, since PHPDocumentor needs the function declarations I can’t actually base the service documentation on service.php, so I’m using apilib.php as the basis for the service documentation.
I created my own PHPDocumentor template, which has been straightforward enough, though I did come across a couple of little issues – nothing too big and nothing that can’t be worked around .
These were the 2 little hacks I needed to put into my template:
- in apilib, I’ve named the functions using camel case, whereas the actual method calls in service.php need to be lower case – so I amended the stylesheet to use: {text-transform:lowercase;} where the function name was displayed
- I also needed to remove the dollar signs from the front of all the PHP parameters, so to do this I just used the Smarty templating command ‘replace’: {$functions[func].params[params].var|replace:’$':”}
I still have some of the documentation to actually write into apilib.php – most notably example service calls for each method and double checking the return descriptions are consistent (and correct). All is working out well and you can see the generated docs on the Cohere site.
