我该如何在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 的状态/用户时间线）的返回值，尤其是针对“获取”和“查看” 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无法满足您的需求，我很乐意探索其他选项 - 请提出建议！

- Alvin Teh

Answer 1

我不知道有什么语法可以为您提供关于在这里使用的JSON字符串的附加结构元素定义。不过，我可以讲解一些基本想法。

由于没有显式参数传递给edit()，因此根本不应该使用@param标签。最好的情况是，可能会包括一个"@ uses UserController::$request"，并说明如何在$data的['args']键中找到任何“作用于edit()的参数”的$ data数组。关于['args']及其结构的所需信息必须是纯文本描述。在这里没有使用某种“结构化文档布局”是没有意义的...这些文档元素只存在于以下两种情况：1）从其他文档链接到它，2）在显示元素时影响文档布局格式。我想我会在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而不仅仅是文本之外，我不知道还能做些什么。我可能会选择仅在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()方法方面有所遗漏。

- ashnazg

Answer 2

我看到你的情况是需要为你的API编写文档而不是记录你的代码。对于API文档，您可以使用特定的工具进行编写，而不是使用像PHPDocumentor这样的工具。 我使用apiary.io来编写API文档，这里有我的示例

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

有很多类似的工具，通常它们是商业化的。我选择 apiary.io 是因为之前它仍然是免费的。

- Dolly Aswin

---

请纠正我，但是Apiary似乎不允许记录单个字段 - 它只显示示例请求和响应主体？我们已经有一个API测试控制台，允许开发人员使用完整的工作样本测试API，但需要一种方法来记录各个字段的详细信息（例如数据类型，可选/必需和描述）。 - Alvin Teh

是的，apiary.io不支持您的需求。我向您展示apiary，因为我认为您没有API控制台，并且我只是通过它拥有我的样例API。我认为您需要像Google API这样的API控制台，它还会显示关于字段的文档，就像您之前所说的那样。但是，如果您的API控制台不支持记录您的API，您可以使用WIKI来制作有关您的API的文档/信息。我在我的项目中已经这样做了。我认为这比使用源代码文档更好。 - Dolly Aswin