Add a documentation form extension (#1234)

* Adding format and example extensions. Getting child type better for collections

Fixing copyrights

Fixing style issues

Fixing style issues

Fixing style issues

* Adding DocumentationExtension

* Adding error for invalid properties

* Reverting switch

* Missing entity break

* Removing unecessary doc

* Removing unecessary method

* Style change

* Adding break for number, integer, and text types

* Extracts the documentation form extension

Form/Extension/DocumentationExtension.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\Form\Extension;
+
+use Symfony\Component\Form\AbstractTypeExtension;
+use Symfony\Component\Form\Extension\Core\Type\FormType;
+use Symfony\Component\Form\FormBuilderInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+/**
+ * @author Aaron Scherer <aequasi@gmail.com>
+ */
+class DocumentationExtension extends AbstractTypeExtension
+{
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder->setAttribute('documentation', $options['documentation']);
+    }
+
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(['documentation' => []])
+            ->setAllowedTypes('documentation', ['array']);
+    }
+
+    public function getExtendedType()
+    {
+        return FormType::class;
+    }
+}

ModelDescriber/FormModelDescriber.php

@@ -64,6 +64,19 @@ final class FormModelDescriber implements ModelDescriberInterface, ModelRegistry
         foreach ($form as $name => $child) {
             $config = $child->getConfig();
             $property = $properties->get($name);
+
+            if ($config->getRequired()) {
+                $required = $schema->getRequired() ?? [];
+                $required[] = $name;
+
+                $schema->setRequired($required);
+            }
+
+            $property->merge($config->getOption('documentation'));
+            if (null !== $property->getType()) {
+                continue; // Type manually defined
+            }
+
             for ($type = $config->getType(); null !== $type; $type = $type->getParent()) {
                 $blockPrefix = $type->getBlockPrefix();
 
@@ -148,20 +161,13 @@ final class FormModelDescriber implements ModelDescriberInterface, ModelRegistry
                 }
 
                 if ($type->getInnerType() && ($formClass = get_class($type->getInnerType())) && !$this->isBuiltinType($formClass)) {
-                    //if form type is not builtin in Form component.
+                    // if form type is not builtin in Form component.
                     $model = new Model(new Type(Type::BUILTIN_TYPE_OBJECT, false, $formClass));
                     $property->setRef($this->modelRegistry->register($model));
 
                     break;
                 }
             }
-
-            if ($config->getRequired()) {
-                $required = $schema->getRequired() ?? [];
-                $required[] = $name;
-
-                $schema->setRequired($required);
-            }
         }
     }
 

Resources/config/services.xml

@@ -45,6 +45,12 @@
 
             <tag name="nelmio_api_doc.model_describer" />
         </service>
+
+        <!-- Form Type Extensions -->
+
+        <service id="Nelmio\ApiDocBundle\Form\Extension\DocumentationExtension">
+            <tag name="form.type_extension" extended-type="Symfony\Component\Form\Extension\Core\Type\FormType"/>
+        </service>
     </services>
 
 </container>

Tests/Functional/Form/UserType.php

@@ -25,7 +25,8 @@ class UserType extends AbstractType
             ->add('dummy', DummyType::class)
             ->add('dummies', CollectionType::class, [
                 'entry_type' => DummyType::class,
-            ]);
+            ])
+            ->add('quz', DummyType::class, ['documentation' => ['type' => 'string', 'description' => 'User type.'], 'required' => false]);
     }
 
     public function configureOptions(OptionsResolver $resolver)

Tests/Functional/FunctionalTest.php

@@ -213,6 +213,10 @@ class FunctionalTest extends WebTestCase
                     'type' => 'array',
                     'example' => sprintf('[{%s}]', DummyType::class),
                 ],
+                'quz' => [
+                    'type' => 'string',
+                    'description' => 'User type.',
+                ],
             ],
             'required' => ['dummy', 'dummies'],
         ], $this->getModel('UserType')->toArray());