Nelmio Api Doc Bundle: Documentating required Parameters

Question

I am currently working with the NelmioApiDocBundle, with which I am not very familiar yet. The API I am writing has to provide a route to change the password of a specific user. The documentation should state, that for changing the password both the old one and the new one are required. Since I did not found an explanation of the difference between Requirementsand Parameters, I guess the first is used for data from the route and the latter is used for the API call itself.

First attempt of archieving such a documentation was to implement a simple Model, which the JMSSerializerBundle then automatically converts:

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

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

}

The Controller accepts the API call via 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)
{
    /* ... */
}

This led to the documentation showing username as Requirement, old_password and new_password as Parameter. To mark those Parameters as required, I added a Symfony Constraint via annotation to the properties:

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

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

}

However, while using these annotations marked the properties as required, it does generate strange output:

Notice the parameters being added twice and in different formats? Adding the @SerializedName("old_password") has no effect. Regarding this ticket, the issue is still not solved.

Another way of accepting data for the action is using a custom form, which indeed marks the properties as required but also generates no proper output. Changing the ChangePasswordParam as custom form:

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';
    }

}

is resulting in this parameter description:

Those parameters should be named just 'old_password' and 'new_password' and I can't figure out how to archieve this.

Thanks in advance

Answer 1

Your @ApiDoc annotation should include an empty input form name field like below:

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

This will remove the form name before the parameters name.