Better Document How the Form Model Describer Works

[cryptiklemur]

Given the following:

<?php

/*
 * This file is part of api-discordservers-com.
 *
 * (c) Aaron Scherer <aequasi@gmail.com>
 *
 * This source file is subject to the license that is bundled
 * with this source code in the file LICENSE
 */

namespace App\Form\Type;

use App\Entity\User;
use Swagger\Annotations\Definition;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

/**
 * @author Aaron Scherer <aequasi@gmail.com>
 *
 * UserForm Class
 * @Definition(required={"id"}, type="object")
 */
class UserForm extends AbstractType
{
    /**
     * {@inheritdoc}
     */
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add("id", TextType::class, ['documentation' => ["required" => true]])
            ->add("email", TextType::class, ['documentation' => ["required" => false]])
            ->add("apiKey", TextType::class, ['documentation' => ["required" => false ]])
            ->add("chargebeeCustomerId", TextType::class, ['documentation' => ["required" => false]]);
    }

    /**
     * {@inheritdoc}
     */
    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(
            [
                'csrf_protection'    => false,
                'data_class'         => User::class,
                'allow_extra_fields' => true,
            ]
        );
    }

    /**
     * {@inheritdoc}
     */
    public function getBlockPrefix()
    {
        return "";
    }
}

The definition that gets generated is:

"UserForm": {
    "required": [
        "id",
        "email",
        "apiKey",
        "chargebeeCustomerId"
    ],
    "properties": {
        "id": {
            "required": true,
            "type": "string"
        },
        "email": {
            "required": false,
            "type": "string"
        },
        "apiKey": {
            "required": false,
            "type": "string"
        },
        "chargebeeCustomerId": {
            "required": false,
            "type": "string"
        }
    },
    "type": "object"
},

[GuilhemN]

@Definition is not parsed on forms. About required, it is automatically detected based on how Symfony sees your field (https://github.com/nelmio/NelmioApiDocBundle/blob/master/ModelDescriber/FormModelDescriber.php#L183), I think you should use the required form option instead of documentation.required.

[cryptiklemur]

Definition was me testing something, forgot to take it out. Documentation suggestions to use the documentation : https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html#symfony-form-types

Maybe the describer should be updated to support required as well?

[GuilhemN]

Maybe the docs should be more precise, in this case you need to update your form to:

public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add("id", TextType::class, ['required' => true])
            ->add("email", TextType::class, ['required' => false])
            ->add("apiKey", TextType::class, ['required' => false ])
            ->add("chargebeeCustomerId", TextType::class, ['required' => false]);
    }