Open Aerendir opened 4 months ago
type
can be an array if we follow the json schema specification, I don't think I can do much here.
Yes, I saw the version 3.1 of the OpenAPI specification: it now allows an array.
The problem is that they changed the type of the field, but this is a breaking change as swagger-php
is now broken.
When api-platform
used the version 3.0, it was possible to use also nelmio/api-docs-bundle
(that, in turn, use swagger-php
).
But, as api-platform
upgraded to version 3.1 of the OpenAPI specification, passing an array with the two possible types, swagger-php
broke.
I see only two possible paths:
api-platform
should allow to choose the version of the OpenAPI specification (3.0|3.1
): this way, the retro-compatibility is maintainedswagger-php
has to upgrade the code to support also the version 3.1
(there is an open task since the 2020 about this support)For the future, for sure api-platform
should take into account that also a minor version may break existing documentations.
The biggest problem, however, is that it is not possible to document external endpoints with api-platform
(not entirely, at least): this is another area where api-platform
should improve (see also https://github.com/api-platform/core/issues/6173#issuecomment-1999362918).
One problem, many causes as of what it seems.
In the meantime, I dropped nelmio/api-docs-bundle
and gone with SwaggerUI integrated in api-platform
, but now I don't have a full nor precise documentation for custom operations (that, unfortunately, cannot be addressed in a clean way using custom processors).
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
I see no sense in autoclosing this "issue"; it should be at least be visible .. That's my main reason why I add a note :)
API Platform version(s) affected: 3.2.* (still present in 3.2.15)
Description
How to reproduce
Create an entity that uses an embeddable.
Trying to get the documentation in Swagger, causes the error.
The error is triggered in
zircote/swagger-php
:https://github.com/zircote/swagger-php/blob/a6d8a93e5daa83d3b959221b0f8f176953d145e9/src/Annotations/Items.php#L53-L56
It expects
$parent->type
bearray
while it actually is anarray
with two values:The fact that
TestEmbeddable::setTestArrayOrNull()
accepts anarray
or anull
value causes$parent->type
to have an array with the two possible acceptable values:array
andnull
.*With `api-platform/core:3.1.` this error didn't happened.**
Possible Solution
I think the problem may be in
ApiPlatform\JsonSchema\SchemaFactory
, but I'm not able to understand what changed that now causes the error.Additional Context
The code that adds the nullability is this:
https://github.com/api-platform/core/blob/bfd759b627990926fddd11c6737af8f993af7bb5/src/JsonSchema/Metadata/Property/Factory/SchemaPropertyMetadataFactory.php#L278-L282
Is here that
$type->type
is not=== 'array'
but is equal to['array', 'null']
and this breakszircote/swagger-php
.I don't know if the issue has to be fixed in
zircote/swagger-php
or here, inapi-platform/core
.Digging deeper in this issue, I noticed the add of
null
is done on purpose (correctly):https://github.com/api-platform/core/commit/d793ffb9228a21655ee35f0b90a959f93281a4cf#diff-32d96682e97b6e04a17576ec737dd6cd19face8782e30713fe1fbf254e9ffaf2R89
https://github.com/api-platform/core/commit/d793ffb9228a21655ee35f0b90a959f93281a4cf#diff-32d96682e97b6e04a17576ec737dd6cd19face8782e30713fe1fbf254e9ffaf2R241
The root cause of the issue
I'm not sure how to deal with this, but it seems to me that ApiPlatform generates OpenApi docs for version 3.1, while
zircote/swagger-php
doesn't still fully support it.Unsure where (and what) to fix this 🤔
Some usefult links
(Possible) Solution
Use the Swagger UI integrated in ApiPlatform:
The types returned are not precise, but, at least, it works...