В настоящее время я работаю с NelmioApiDocBundle, с которым я еще не очень знаком. API, который я пишу, должен предоставить маршрут для изменения пароля конкретного пользователя. В документации должно быть указано, что для смены пароля требуется как старый, так и новый пароль. Так как я не нашел объяснения разницы между Requirements
а также Parameters
Я полагаю, что первый используется для данных из маршрута, а второй — для самого вызова API.
Первой попыткой архивации такой документации было реализовать простую модель, которую затем JMSSerializerBundle автоматически конвертирует:
class ChangePasswordParam
{
/**
* @Type("string")
* @var string
*/
protected $oldPassword;
/**
* @Type("string")
* @var string
*/
protected $newPassword;
}
Контроллер принимает вызов 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
как требование, 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, и я не могу понять, как это заархивировать.
заранее спасибо
Ваша аннотация @ApiDoc должна включать пустое поле имени формы ввода, как показано ниже:
* @ApiDoc(
* description="Changes the password of a User",
* input= {
* "class" = "FQCN\ChangePasswordParam",
* "name" = ""* }
* )
Это удалит имя формы перед именем параметра.
Других решений пока нет …