Nelmio Api Doc Bundle: Documentating required Parameters - php

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.