如何在phpDocumentor 2中记录JSON参数和返回类型？

Question

我有一个使用CakePHP编写的PHP REST API作为项目的一部分。所有API端点都作为控制器中的单个方法存在，并接受JSON字符串中的参数和返回值。我想弄清楚我应该如何记录这些方法的参数和返回类型phpDocumentor2。

例如，如果我在UsersController有一个编辑（）方法，对于用户模型，其骨架更新指定的字段看起来像这样（我已经简化为简洁的代码）：

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; 
} 

我可能返回以下JSON请求修改用户的姓氏和名字：

{ 
    "id": 1 
    "first_name": "John" 
    "last_name": "Doe" 
} 

如果API调用成功，该方法将返回：

{ 
    "status": 1 
} 

而如果不成功，也许是由于失败的数据验证，该方法可能会返回类似：

{ 
    "status": 0 
    "code": 202, 
    "messages": { 
     "first_name": { 
      "Numeric characters are not allowed." 
     } 
    } 
} 

我明白，我可以使用的phpDocumentor的@return和@param分别记录返回值和参数，但从文档中，没有任何关于JSON返回的内容。

我可以举例来说，文档返回类型为

@return $value string A JSON string that contains the status code and error messages if applicable. 

但我几乎认为适当，特别是涉及更复杂的数据结构返回（想象类似的东西Twitter的状态/ user_timeline），特别是对于“得到“和”查看“API方法。

在另一方面，参数，我不知道这是否是正确的，我来为每个参数（考虑到所有的参数都包裹在一个JSON字符串）这样一行：

@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. 

如果phpDocumentor无法满足此需求，我愿意探索其他选项 - 只是建议！

Answer 1

我不知道任何语法，可以给你额外的结构元素定义关于你在这里玩的JSON字符串。但我可以解释一些基本想法。

由于没有显式参数传递给edit（），所以不应该使用@param标签。充其量，可能包含一个“@uses UserController :: $ request”，其中的描述解释了其$ data数组应该如何在$ data的['args']键中找到任何“用于edit（）的参数”。解释['args']及其结构所需的信息必须是纯文本描述。在这里进行某种“结构化文档布局”毫无意义...这样的文档元素只存在于1）与其他文档链接，2）在显示元素时影响文档布局格式。我想我会接近它像这样，在对文档块编辑（）：

* @uses UserController::$request 
*   $request has its own $data array, whose ['args'] key 
*   should contain a JSON value. In the JSON, keys represent 
*   the fields to edit, values are the new values. 

至于回报，因为有一个实际回报这里，而不仅仅是幕后的正在做的修改，我将使用一个真正的@return标签：

* @return string JSON that indicates success/failure of the update, 
*    or JSON that indicates an error occurred. 

可以肯定这个从文档能够呈现JSON像实际JSON，而不仅仅是文字扩大在每个点显示JSON字符串的例子，但除了，我不明白你还有什么可以追求的。我可能会选择在docblock的Long Description中仅显示状态返回的JSON示例，并将读者引用到createError（）方法的文档中，以查看错误的JSON布局，而不是试图将它们全部塞进标签中。

/** 
* edit() method 
* 
* The edit() method examines values already set elsewhere, acts on the edits requested 
* by those values, and returns an indication of whether or not the edits succeeded. 
* 
* An array key of $data['args'] must be set in the UserController::$request object. 
* It must contain a JSON string that lists the fields to update and the values to use. 
* 
* Example: 
* <code> 
* { 
*  "id": 1 
*  "first_name": "John" 
*  "last_name": "Doe" 
* } 
* </code> 
* 
* "id" is required, while other fields are optional. 
* 
* The JSON string that is returned by edit() will normally indicate whether or not 
* the edits were performed successfully. 
* 
* Success: 
* <code> 
* { 
*  "status": 1 
* } 
* </code> 
* Failure: 
* <code> 
* { 
*  "status": 0 
* } 
* </code> 
* 
* In the case of validation errors with the values used in the updates, 
* a JSON error string would be returned, in the format generated 
* by the createError() method. 
* 
* @return string JSON that indicates success/failure of the update, 
*    or JSON that indicates an error occurred. 
* 
* @uses UserController::$request 
* @see UserController::createError() 
*/ 

你可能觉得这是很多就摆在那里，但你要明白，你要解释一些幕后的巫术到编码器/消费者是阅读的文档。而不是用直接的参数调用方法，你必须解释用户必须以迂回的方式提供参数。详细描述中的冗长可以避免用户感觉像在理解如何正确使用edit（）方法时缺少某些东西。

Answer 2

我在这种情况下看到，您的需求是为您的API制作文档，而不是记录您的代码。对于API文档，您可以使用特定的工具，而不是使用PHPDocumentor之类的工具。 我用apiary.io的API文档，这里的矿

http://docs.dollyaswinnet.apiary.io/

有很多这样的工具样品，并且通常他们是商业。我选择apiary.io是因为它之前还是空闲的。