Nelmio Api Doc Bundle：记录所需参数

Posted 2023-02-16

【中文标题】Nelmio Api Doc Bundle：记录所需参数

【英文标题】：Nelmio Api Doc Bundle: Documentating required Parameters

【发布时间】：2015-11-25 08:12:10

【问题描述】：

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

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

class ChangePasswordParam

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

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

Controller 通过这个 action 方法接受 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 显示为 Requirement，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”，我不知道如何归档。

提前致谢

【问题讨论】：

我不明白为什么后者应该在没有“change_password”前缀的情况下显示。这就是表单对象的表示方式。如果您只想使用请求参数，您可以不使用输入而单独指定它们

这是另一个同样问题的问题：github.com/nelmio/NelmioApiDocBundle/issues/867

【参考方案1】：

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

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

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

【讨论】：

它确实删除了表单名称，但它也忽略了实体上的序列化配置，因此属性名称不匹配（在我的情况下，它是驼峰式而不是破折号分隔的小写）