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

Question

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

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

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的statuses/user_timeline)，特别是对于"get“和"view”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标记。在最好的情况下，可以在$data的'args‘键中包含一个“@ UserController::$request”和一个描述，解释它的$data数组应该如何找到任何“编辑()操作的参数”。解释“args”及其结构所需的信息必须是纯文本描述。在这里有一些“结构化文档布局”是没有意义的…这样的单据元素只存在于1)从其他单据链接，2)在显示元素时影响单据布局格式。我想我会这样处理它，在edit()的docblock中：

* @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的详细描述中的status return 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是因为它之前仍然是免费的。