Nelmio Api Doc Bundle：記錄所需的參數

Question

我目前正在使用NelmioApiDocBundle，我還不熟悉它。 我寫的API必須提供一個更改特定用戶密碼的路徑。 文檔應說明，更改密碼既需要舊密碼，也需要新密碼。 由於我沒有找到Requirements和Parameters之間差異的解釋，我想第一個用於路由數據，后者用於API調用本身。

首次嘗試提供這樣的文檔是為了實現一個簡單的模型，然后JMSSerializerBundle自動轉換：

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

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

}

Controller通過此操作方法接受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 Constraint：

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

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

}

但是，雖然使用這些注釋標記了所需的屬性，但它確實會生成奇怪的輸出：

注意參數被添加兩次並以不同的格式？ 添加@SerializedName("old_password")無效。 關於這張票 ，問題仍未解決。

接受動作數據的另一種方法是使用自定義表單，它確實根據需要標記屬性，但也不生成正確的輸出。 將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" = ""
*  }
* )

這將刪除參數名稱前的表單名稱。