Nelmio Api 文档包：记录所需参数

Question

我目前正在使用 NelmioApiDocBundle，对此我还不是很熟悉。我写的 API 必须提供更改特定用户密码的途径。文档应该说明，要更改密码，旧密码和新密码都是必需的。由于我没有找到 Requirements 和 Parameters 之间区别的解释，我猜前者用于路由数据，后者用于 API 调用本身。

归档此类文档的第一次尝试是实现一个简单的模型，然后 JMSSerializerBundle 会自动转换该模型：

class ChangePasswordParam
{
    /**
     * @Type("string")
     * @var string
     */
    protected $oldPassword;

    /**
     * @Type("string")
     * @var string
     */
    protected $newPassword;

}

控制器通过此操作方法接受 API 调用：

/**
 * Changes the password for a specific user.
 *
 * @Post("/{username}/changepassword")
 * @View()
 * @ApiDoc(
 *  description="Changes the password of a User",
 *  input="FQCN\ChangePasswordParam"
 * )
 *
 * @param string              $username
 * @param ChangePasswordParam $passwordParam
 *
 * @return Response
 */
public function changePasswordAction($username, ChangePasswordParam $passwordParam)
{
    /* ... */
}

这导致文档显示 username 作为要求，old_password 和 new_password 作为参数。为了根据需要标记这些参数，我通过注释向属性添加了一个 Symfony 约束：

class ChangePasswordParam
{
    /**
     * @Type("string")
     * @Assert\NotNull()
     * @var string
     */
    protected $oldPassword;

    /**
     * @Type("string")
     * @Assert\NotNull()
     * @var string
     */
    protected $newPassword;

}

但是，在使用这些注释将属性标记为必需时，它确实会生成奇怪的输出：

注意到参数以不同的格式添加了两次？添加 @SerializedName("old_password") 没有任何效果。关于this ticket，问题依旧没有解决

接受操作数据的另一种方法是使用自定义表单，它确实将属性标记为必需，但也不会生成正确的输出。将 ChangePasswordParam 更改为自定义表单：

class ChangePasswordParam extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('old_password', 'text');
        $builder->add('new_password', 'text');
    }


    /**
     * Returns the name of this type.
     *
     * @return string The name of this type
     */
    public function getName()
    {
        return 'change_password';
    }

}

导致此参数说明：

这些参数应该只命名为 'old_password' 和 'new_password'，我不知道如何实现它。

提前致谢

Answer 1

您的@ApiDoc 注释应包含一个空的输入表单名称字段，如下所示：

* @ApiDoc(
*  description="Changes the password of a User",
*  input= {
*    "class" = "FQCN\ChangePasswordParam",
*    "name" = ""
*  }
* )

这将删除参数名称之前的表单名称。

Nelmio Api 文档包：记录所需参数

Nelmio Api Doc Bundle: Documentating required Parameters

php

symfony

fosrestbundle

jmsserializerbundle

nelmioapidocbundle