mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-09 02:59:27 +03:00
14d1021c8b
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.
94 lines
3.3 KiB
PHP
94 lines
3.3 KiB
PHP
<?php
|
|
|
|
/*
|
|
* This file is part of the NelmioApiDocBundle.
|
|
*
|
|
* (c) Nelmio <hello@nelm.io>
|
|
*
|
|
* For the full copyright and license information, please view the LICENSE
|
|
* file that was distributed with this source code.
|
|
*/
|
|
|
|
namespace Nelmio\ApiDocBundle\Extractor\Handler;
|
|
|
|
use Nelmio\ApiDocBundle\DataTypes;
|
|
use Nelmio\ApiDocBundle\Extractor\HandlerInterface;
|
|
use Nelmio\ApiDocBundle\Annotation\ApiDoc;
|
|
use Symfony\Component\Routing\Route;
|
|
use Symfony\Component\Validator\Constraint;
|
|
use Symfony\Component\Validator\Constraints\Regex;
|
|
use FOS\RestBundle\Controller\Annotations\RequestParam;
|
|
use FOS\RestBundle\Controller\Annotations\QueryParam;
|
|
|
|
class FosRestHandler implements HandlerInterface
|
|
{
|
|
/**
|
|
* @inheritdoc
|
|
*/
|
|
public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method)
|
|
{
|
|
foreach ($annotations as $annot) {
|
|
if ($annot instanceof RequestParam) {
|
|
|
|
$requirements = $this->handleRequirements($annot->requirements);
|
|
$annotation->addParameter($annot->name, array(
|
|
'required' => $annot->strict && $annot->default === null,
|
|
'dataType' => $requirements,
|
|
'actualType' => $this->inferType($requirements),
|
|
'subType' => null,
|
|
'description' => $annot->description,
|
|
'readonly' => false
|
|
));
|
|
} elseif ($annot instanceof QueryParam) {
|
|
if ($annot->strict && $annot->nullable === false && $annot->default === null) {
|
|
$annotation->addRequirement($annot->name, array(
|
|
'requirement' => $this->handleRequirements($annot->requirements),
|
|
'dataType' => '',
|
|
'description' => $annot->description,
|
|
));
|
|
} elseif ($annot->default !== null) {
|
|
$annotation->addFilter($annot->name, array(
|
|
'requirement' => $this->handleRequirements($annot->requirements),
|
|
'description' => $annot->description,
|
|
'default' => $annot->default,
|
|
));
|
|
} else {
|
|
$annotation->addFilter($annot->name, array(
|
|
'requirement' => $this->handleRequirements($annot->requirements),
|
|
'description' => $annot->description,
|
|
));
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Handle FOSRestBundle requirements in order to return a string.
|
|
*
|
|
* @param mixed $requirements
|
|
* @return string
|
|
*/
|
|
private function handleRequirements($requirements)
|
|
{
|
|
if (is_object($requirements) && $requirements instanceof Constraint) {
|
|
if ($requirements instanceof Regex) {
|
|
return $requirements->getHtmlPattern();
|
|
}
|
|
$class = get_class($requirements);
|
|
|
|
return substr($class, strrpos($class, '\\')+1);
|
|
}
|
|
|
|
return (string) $requirements;
|
|
}
|
|
|
|
public function inferType($requirement)
|
|
{
|
|
if (DataTypes::isPrimitive($requirement)) {
|
|
return $requirement;
|
|
}
|
|
|
|
return DataTypes::STRING;
|
|
}
|
|
}
|