Embedded objects on DTO aren't documented since 2.6.0

[RobinHoutevelts]

API Platform version(s) affected: >=2.6.0

Description
In 2.5.10 this DTO resulted in the following documentation output:

namespace App\ApiPlatform\Entity\Venue;

class Venue
{
    /**
     * The title of the venue.
     *
     * @Groups({"venue:read", "venue:write"})
     * @Assert\NotBlank()
     * @var string
     */
    public string $title;

    /**
     * The alternative name of the venue.
     *
     * @Groups({"venue:read", "venue:write"})
     */
    public ?string $alternativeName;

    /**
     * The contact information of the venue.
     *
     * @Groups({"venue:read", "venue:write"})
     * @Assert\Valid()
     */
    public Contact $contact;
}

class Contact
{
    /**
     * The website.
     *
     * @Groups({"venue:read", "venue:write"})
     * @Assert\Url()
     */
    public ?string $website;

    /**
     * The email address.
     *
     * @Groups({"venue:read", "venue:write"})
     * @Assert\Email()
     */
    public ?string $email;
}

ApiResource class Venue:

<?php

use App\ApiPlatform\Entity\Venue\Venue as VenueDto;

/**
 * @ApiResource(
 *     output=VenueDto::CLASS,
 *     input=VenueDto::CLASS,
 *     normalizationContext={"groups"={"venue:read"}},
 *     denormalizationContext={"groups"={"venue:write"}},
 *     collectionOperations={
 *         "get"={
 *              "normalization_context"={"groups"={"venue:collection:read"}}
 *         },
 *         "post"={
 *              "denormalization_context"={"groups"={"venue:write"}}
 *         }
 *     },
 *     itemOperations={"get", "put", "delete"}
 * )
 * @ORM\Entity(repositoryClass=VenueRepository::class)
 */
class Venue
{
    ...
}

But since >=2.6.0 it no longer documents the embedded Contact class:

How to reproduce

https://github.com/RobinHoutevelts/apipf_regression_dto_embedded_object

[RobinHoutevelts]

Click here to see me nag about something that has nothing to do with this issue

It seems the requests do work. So it's just something with the swagger documentation.

However when using a JSON:API response the nested objects are treated like nested resources.

Even though I never added the #ApiResource annotation on the Contact class, it gets a ( random ) id and the Contact type.

Actual result

{
    "data": {
        "id": "/api/venues/dd8058c4-31f7-4ac2-a9bd-2f2548e67315",
        "type": "Venue",
        "attributes": {
            "id": "dd8058c4-31f7-4ac2-a9bd-2f2548e67315",
            "title": "My kitchen",
            "alternativeName": null,
            "contact": {
                "data": {
                    "id": 2722,
                    "type": "Contact",
                    "attributes": {
                        "website": null,
                        "email": null,
                        "phone": "123456789",
                        "countryCallingCode": 32
                    }
                }
            }
        }
    }
}

Expected result

{
    "data": {
        "id": "/api/venues/dd8058c4-31f7-4ac2-a9bd-2f2548e67315",
        "type": "Venue",
        "attributes": {
            "id": "dd8058c4-31f7-4ac2-a9bd-2f2548e67315",
            "title": "My kitchen",
            "alternativeName": null,
            "contact": {
                "website": null,
                "email": null,
                "phone": "123456789",
                "countryCallingCode": 32
            }
        }
    }
}

Edit: I worked around this by using a custom item normalizer for those nested objects. But the issue in parent comment is still preventing me from upgrading to 2.6.x

[burned42]

I have the same issue but with enums (myclabs/enum). In 2.6 the openapi docs just include a description. In 2.5 there was also a $ref pointing to the model/schema of the Enum class.

I also have one property which is an array of enums and there it has the description but also still "type": "array" and "items: { "$ref": "..." }", so for that one it's not broken, but has the same behavior on 2.5 and 2.6.

[RobinHoutevelts]

I managed to trace the bug to this PR #3957 which fixes issue #3945

This is being said in that issue:

core/src/JsonSchema/SchemaFactory.php

Line 229 in 9e6ae81

$propertySchema = new \ArrayObject($propertySchema + $valueSchema);

So, I would suggest the following diff:

- $propertySchema = new \ArrayObject($propertySchema + $valueSchema);
+ if (count($propertySchema) > 0 && array_key_exists('$ref', $valueSchema)) {
+    $propertySchema = new \ArrayObject($propertySchema);
+ } else {
+     $propertySchema = new \ArrayObject($propertySchema + $valueSchema);
+ }

Which means the following: if we have other keys in $propertySchema- we don't add $ref from $valueSchema that will override everything.

However, having a filled $propertySchema doesn't always mean you want to override the openapi_context.

In my case $propertySchema contains the description of my property. Yet I still expect the $ref to be set.

---

A possible solution might be to instead check for the type key on $propertySchema.

I think it still satisfies #3945

I'll make a PR tomorrow so we can discuss it.

- if (count($propertySchema) > 0 && array_key_exists('$ref', $valueSchema)) {
+ if (\array_key_exists('type', $propertySchema) && \array_key_exists('$ref', $valueSchema)) {
     $propertySchema = new \ArrayObject($propertySchema);
  } else {
      $propertySchema = new \ArrayObject($propertySchema + $valueSchema);
  }

[alanpoulain]

This solution seems OK to me.