Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Stop Model Property Description When a Schema Type or Ref is Already …
…Defined (#1978) * Return a Result Object from AnnotationsReader::updateDefinition This is so we can make a decision on whether or not a schema's type or ref has been manually defined by a user via an `@OA\Schema` annotation as something other than an object. If it has been defined, this bundle should not read model properties any further as it causes errors. I put this in AnnotationReader as it seemed the most flexible in the long run. It could have gone in `OpenApiAnnotationsReader`, but then any additional things added to `updateDefinition` could be left out of the decision down the road. This is also a convenient place to decide this once for `ObjectModelDescriber` and `JMSModelDescriber`. * Stop Model Describer if a Schema Type or Ref Has Been Defined Via the result object added in the previous commit. This lets user "short circuit" the model describers by manually defining the schema type or ref on a plain PHP object or form. For example, a collection class could be defined like this: /** * @OA\Schema(type="array", @OA\Items(ref=@model(type=SomeEntity::class))) */ class SomeCollection implements \IteratorAggregate { } Previously the model describer would error as it tries to merge the `array` schema with the already defiend `object` schema. Now it will prefer the array schema and skip reading all the properties of the object. * Add a Documentation Bit on Stopping Property Description * Mark UpdateClassDefinitionResult as Internal
- Loading branch information
1 parent
6ac4f07
commit da02f3a
Showing
13 changed files
with
366 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
41 changes: 41 additions & 0 deletions
41
ModelDescriber/Annotations/UpdateClassDefinitionResult.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
<?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\ModelDescriber\Annotations; | ||
|
||
/** | ||
* result object returned from `AnnotationReader::updateDefinition` as a way | ||
* to pass back information about manually defined schema elements. | ||
* | ||
* @internal | ||
*/ | ||
final class UpdateClassDefinitionResult | ||
{ | ||
/** | ||
* Whether or not the model describer shoudl continue reading class properties | ||
* after updating the open api schema from an `OA\Schema` definition. | ||
* | ||
* Users may maually define a `type` or `ref` on a schema, and if that's the case | ||
* model describers should _probably_ not describe any additional properties or try | ||
* to merge in properties. | ||
*/ | ||
private $shouldDescribeModelProperties; | ||
|
||
public function __construct(bool $shouldDescribeModelProperties) | ||
{ | ||
$this->shouldDescribeModelProperties = $shouldDescribeModelProperties; | ||
} | ||
|
||
public function shouldDescribeModelProperties(): bool | ||
{ | ||
return $this->shouldDescribeModelProperties; | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
<?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\Tests\Functional\Entity; | ||
|
||
use ArrayIterator; | ||
use IteratorAggregate; | ||
use OpenApi\Annotations as OA; | ||
|
||
/** | ||
* @OA\Schema(type="array", @OA\Items(type="string")) | ||
*/ | ||
class EntityWithAlternateType implements IteratorAggregate | ||
{ | ||
/** | ||
* @var string | ||
*/ | ||
public $ignored = 'this property should be ignored because of the annotation above'; | ||
|
||
public function getIterator(): ArrayIterator | ||
{ | ||
return new ArrayIterator([ | ||
'abc', | ||
'def', | ||
]); | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
<?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\Tests\Functional\Entity; | ||
|
||
use OpenApi\Annotations as OA; | ||
|
||
/** | ||
* @OA\Schema(type="object") | ||
*/ | ||
class EntityWithObjectType | ||
{ | ||
/** | ||
* @var string | ||
*/ | ||
public $notIgnored = 'this should be read'; | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
<?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\Tests\Functional\Entity; | ||
|
||
use OpenApi\Annotations as OA; | ||
|
||
/** | ||
* @OA\Schema(ref="#/components/schemas/Test") | ||
*/ | ||
class EntityWithRef | ||
{ | ||
/** | ||
* @var string | ||
*/ | ||
public $ignored = 'this property should be ignored because of the annotation above'; | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
<?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\Tests\Functional\Form; | ||
|
||
use OpenApi\Annotations as OA; | ||
use Symfony\Component\Form\AbstractType; | ||
use Symfony\Component\Form\Extension\Core\Type\InputType; | ||
use Symfony\Component\Form\FormBuilderInterface; | ||
|
||
/** | ||
* @OA\Schema(type="string") | ||
*/ | ||
class FormWithAlternateSchemaType extends AbstractType | ||
{ | ||
public function buildForm(FormBuilderInterface $builder, array $options) | ||
{ | ||
$builder | ||
->add('ignored', InputType::class, [ | ||
'required' => false, | ||
]); | ||
} | ||
} |
Oops, something went wrong.