This is the result of https://github.com/nelmio/NelmioApiDocBundle/issues/410.
This PR aims to provide a uniform way of declaring data-types of parameters for
parsers and handlers to follow. In turn, this would allow formatters to
determine data-types in a cleaner and less volatile manner. (See use-case that
can be improved with this PR:
https://github.com/nelmio/NelmioApiDocBundle/blob/master/Formatter/AbstractFormatter.php#L103)
This is possible by the addition two properties to each property item in
`response`, and `parameters` fields in each API endpoint produced by the
`ApiDocExtractor`:
* `actualType` Contains a value from one of the `DataTypes` class constants.
* `subType` Can contain either `null`, or any other `DataTypes` class constant.
This is relevant when the `actualType` is a `DataTypes::COLLECTION`, wherein
`subType` would specify the type of the collection items. It is also relevant
when `actualType` is a `DataTypes::MODEL`, wherein `subType` would contain an
identifier of the model (the FQCN or anything the parser would wish to specify)
Examples:
```php
array(
'id' => array(
'dataType' => 'integer',
'actualType' => DataTypes::INTEGER,
'subType' => null,
),
'profile' => array(
'dataType' => 'object (Profile)',
'actualType' => DataTypes::MODEL,
'subType' => 'Foo\Entity\Profile',
'children' => array(
'name' => array(
'dataType' => 'string',
'actualType' => DataTypes::STRING,
'subType' => null,
),
'birthDate' => array(
'dataType' => 'date',
'actualType' => DataTypes::DATE,
'subType' => null,
),
)
),
'languages' => array(
'dataType' => 'array of strings',
'actualType' => DataTypes::COLLECTION,
'subType' => DataTypes::STRING,
),
'roles' => array(
'dataType' => 'array of choices',
'actualType' => DataTypes::COLLECTION,
'subType' => DataTypes::ENUM,
),
'groups' => array(
'dataType' => 'array of objects (Group)',
'actualType' => DataTypes::COLLECTION,
'subType' => 'Foo\Entity\Group',
),
'profileRevisions' => array(
'dataType' => 'array of objects (Profile)',
'actualType' => DataTypes::COLLECTION,
'subType' => 'Foo\Entity\Profile',
),
'address' => array(
'dataType' => 'object (a_type_a_custom_JMS_serializer_handler_handles)',
'actualType' => DataTypes::MODEL,
'subType' => 'a_type_a_custom_JMS_serializer_handler_handles',
),
);
```
When a formatter omits the `dataType` property or leaves it blank, it is
inferred within `ApiDocExtractor` before everything is passed to formatters.
Move logic to extract data in the Extractor
Remove logic in the AbstractFormatter
Use ApiDoc class as data container
Update tests
Add test to prove the bug with FOSRestBundle annotations (\\d+ instead of \d+)
