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

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 的状态/用户时间线），特别是对于“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

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

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

这样的工具有很多，而且通常是商业的。我选择 apiary.io 是因为它之前还是免费的。

Answer 2

我不知道有任何语法可以为您提供关于您在此处使用的 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 而不仅仅是文本之外，我看不出您还能追求什么.我可能会选择在文档块的长描述中仅显示状态返回 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() 方法时遗漏了一些东西。