Question

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

例如，如果我在UsersController中有一个edit（）方法，它更新User模型的指定字段，其骨架如下所示（为简洁起见，我简化了代码）：

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']及其结构所需的信息必须是纯文本描述。这里有一些“结构化文档布局”没有意义......这样的doc元素只存在于1）与其他文档链接，2）在显示元素时影响doc布局格式。我想我会在docblock for edit（）中接近它：

* @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的长描述中显示状态返回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，因为它之前仍然是免费的。

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

2 个答案: