Комплект документов Nelmio Api: документирование необходимых параметров

Question

В настоящее время я работаю с 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', и я не могу понять, как это заархивировать.

заранее спасибо

Answer 1

Ваша аннотация @ApiDoc должна включать пустое поле имени формы ввода, как показано ниже:

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

Это удалит имя формы перед именем параметра.