NelmioApiDocBundle根据输入注释生成一个额外的参数

Question

In my symfony2 project, I installed FOSRestBundle and NelmioApiDocBundle in order to create an api.

I have a strange behavior with my POST route : when I add the annotation property "input", the Nelmio bundle generates an extra parameter in addition to my form fields. This extra parameter is the form entity itself.

Screen :

I tried to debug the moment when Nelmio parses my route's annotations :

We can notice the parameters property is set.

Here is the annotations of my post action method :

/**
 * Create a Punchline from the submitted data.
 *
 * @ApiDoc(
 *   description = "Creates a new punchline from the submitted data.",
 *   input = {
 *      "class" = "Punchline\BackendBundle\Form\Type\PunchlineType",
 *      "options" = {"method" = "POST"}
 *   },
 *   statusCodes = {
 *     201 = "Returned when successful",
 *     400 = "Returned when the form has errors"
 *   }
 * )
 *
 * @param Request $request the request object
 *
 * @return Response
 */
public function postPunchlineAction(Request $request)

And this is my FormType :

<?php

namespace Punchline\BackendBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;

class PunchlineType extends AbstractType
{
    /**
     * @param FormBuilderInterface $builder
     * @param array $options
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('content', 'text')
            ->add('author', 'author_selector')
            ->add('single', 'single_selector')
        ;
    }

    /**
     * @param OptionsResolverInterface $resolver
     */
    public function setDefaultOptions(OptionsResolverInterface $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => 'Punchline\BackendBundle\Entity\Punchline'
        ));
    }

    /**
     * @return string
     */
    public function getName()
    {
        return 'punchline';
    }
}

From the NelmioApiDocBundle documentation :

If you set input, then the bundle automatically extracts parameters based on the given type, and determines for each parameter its data type, and if it's required or not.

I tried to remove the form fields and the parameter sill remains... I didn't found where I set this required parameter.

Answer 1

From the documentation you posted:

Form Types Features

Even if you use FormFactoryInterface::createNamed('', 'your_form_type') the documentation will generate the form type name as the prefix for inputs (your_form_type[param] ... instead of just param).

You can specify which prefix to use with the name key in the input section:

input = { "class" = "your_form_type", "name" = "" }

Try modifying your @ApiDoc like this:

 * @ApiDoc(
 *   description = "Creates a new punchline from the submitted data.",
 *   input = {
 *      "class" = "Punchline\BackendBundle\Form\Type\PunchlineType",
 *      "options" = {"method" = "POST"},
 *      "name" = ""
 *   },
 *   statusCodes = {
 *     201 = "Returned when successful",
 *     400 = "Returned when the form has errors"
 *   }
 * )

Answer 2

Don't put the FormType as input, but the Entity class that your Type fill. if you think about it, your API consumer does not have to know how the data is treated, they only care about the abstract entity they're providing.