StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POHow should I document JSON parameters and return types in phpDocumentor 2?
text
Body
copied!<p>I have a PHP REST API written with CakePHP as part of a project. All of the API endpoints exist as individual methods in controllers and accept arguments and return values in a JSON string. I am trying to figure how I should document the parameters and return types for these methods phpDocumentor2.</p> <p>For example, if I have a edit() method in UsersController that updates specified fields for the User model, whose skeleton looks like this (I've simplified the code for brevity):</p> <pre><code>public function edit() { //Get arguments $args = $this->request->data['args']; $id = $args['id']; //Perform processing if (!$this->User->exists($id)) { $data = $this->createError(300); } else { $this->User->id = $id; $saveData = array(); if (isset([$args['first_name'])) { $saveData['User']['first_name'] = $args['first_name']; } if (isset([$args['last_name'])) { $saveData['User']['last_name'] = $args['last_name']; } $isSaved = $this->User->save($saveData); if (count($this->User->validationErrors) > 0) { $data = $this->createError(202, $this->User->validationErrors); } else { $data = array('status' => $isSaved ? 1 : 0); } } //Output data return $data; } </code></pre> <p>I might send a request with the following JSON to modify the user's first and last names.:</p> <pre><code>{ "id": 1 "first_name": "John" "last_name": "Doe" } </code></pre> <p>If the API call is successful, the method will return:</p> <pre><code>{ "status": 1 } </code></pre> <p>And if it is unsuccessful, perhaps to due to failed data validation, the method might return something like:</p> <pre><code>{ "status": 0 "code": 202, "messages": { "first_name": { "Numeric characters are not allowed." } } } </code></pre> <p>I understand that I can use phpDocumentor's @return and @param to document return values and parameters respectively, but from the documentation, nothing is stated about JSON returns.</p> <p>I could for instance, document the return type as</p> <pre><code>@return $value string A JSON string that contains the status code and error messages if applicable. </code></pre> <p>But I hardly consider that proper, especially for returns involving more complex data structures (imagine something similar Twitter's statuses/user_timeline) particularly for the "get" and "view" API methods.</p> <p>On the other hand, for parameters, I'm not sure if it is correct for me to create one line for each parameter (considering all the parameters are wrapped in one JSON string) like:</p> <pre><code>@param string $id The ID of the user to be updated. @param string $first_name optional The first name of the user. @param string $last_name optional The last name of the user. </code></pre> <p>I am open to exploring other options if phpDocumentor cannot fulfill this need - just suggest!</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload