Nelmio Api Doc Bundle: documentation on the required parameters

Question

I am currently working with a NelmioApiDocBundle, which I am not very familiar with yet. The API I am writing should provide a route for changing the password of a specific user. The documentation should indicate that changing the password requires both old and new. Since I did not find an explanation of the difference between Requirementsand Parameters, I assume that the former is used for route data, and the latter is used for the API call itself.

The first attempt to archive such documentation was to implement a simple model that the JMSSerializerBundle automatically converts:

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

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

}

The controller accepts an API call through this action method:

/**
 * 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") . , .

, , . 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" = ""
*  }
* )

.