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

I don not see why the latter should display without the 'change_password' prefix. This is how the form object is represented. If you want to use just request parameters you could do it without using the input and just specifying them separately — Bizmate, Oct 18 '15 at 12:21
Here is another issue with the same problem: https://github.com/nelmio/NelmioApiDocBundle/issues/867 — Dmitriy Simushev, Apr 19 '17 at 12:50

score 2 · Accepted Answer · answered May 12 '16 at 08:55

2

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.

answered May 12 '16 at 08:55

d23

186
8

1

It does indeed remove the form name but it also ignores the serialisation config on the entity so the property-names do not match (in my case it's camel-case instead of dash-separated lower-case) – marsbear May 29 '16 at 22:08

Nelmio Api Doc Bundle: Documentating required Parameters

1 Answers1