Wrong Swagger types when creating relations on a single POST

[quentinus95]

API Platform version(s) affected: 2.5.1

Description
When allowing to create relations using denormalization_context, the generated Swagger documentation is a list of strings instead of an union of strings and objects.

How to reproduce
It's easy to reproduce the issue on the demo. We have by default the following types (which are already wrong) on the Book entity:

{
  //...
  "reviews": [
      {
        "body": "string",
        "rating": 0,
        "author": "string",
        "publicationDate": "2020-03-02T10:31:24.895Z"
      }
  ]
}

but the expected types should be an array of unions (oneOf) of the above type with strings (in the case IRIs are passed).

Now, for the most annoying bug:

In Review, we have the following annotations on body:

    /**
     * @var string The actual body of the review
     *
     * @ORM\Column(type="text", nullable=true)
     * @Groups({"review:read", "book:read"})
     * @ApiProperty(iri="http://schema.org/reviewBody")
     */
    public $body;

If you remove the book:read group, then the generated swagger type showed above is turned into:

{
  //...
  "reviews": ["string"]
}

Which does not make any sense. I have removed here an annotation related to the normalizationContext and it changes the types which are related to the denormalization_context. This change should not have impacted the expected type on POST.

Possible Solution
Generated types should be an union type of string (to allow the user to passe an IRI) and the body matching the denormalization configuration. In the case of the demo, the change shown above should not have impacted the JSON types.

Additional Context
Before the change (good but should be an union):

After the change (string only despite allowing creating the relation directly):

[teohhanhui]

Please update to the latest release. This has already been fixed in #3309.

Never mind. It seems to be a different issue. Sorry for closing before reading properly.

[teohhanhui]

The reviews.*.body bug above is the same as #3146 and will be fixed by #3425

[teohhanhui]

As for the oneOf, while that will be more correct, I'm not sure the tradeoff is worth it, because Swagger UI doesn't support that. See swagger-api/swagger-ui#3803

[quentinus95]

@teohhanhui thanks for your answer.

I don't believe Swagger UI support for the JSON Schema feature is a blocker for this change to be implemented.

We massively rely on those types as the actual definition of the API, and use it to generate strongly typed clients and docs.

Having the right types in the OpenAPI spec is a prerequisite to have a good interoperability between apps in different languages. For instance, many of our developers don't spend too much time on the Swagger UI, they already have tooling to generate all the expected types from the API (plus, some of them actually comment the generated types so the entire documentation is direclty in the IDE).

The current string behavior is a bug as those developers must bypass their own type checkers to use APIs produced with API-Platform.

I hope this gives you more context about why I believe this bug should be fixed to improve the autodiscoverability of the types exposed by the API.

[teohhanhui]

I understand your use case, but this would affect everyone who uses API Platform. We need to find a sweet spot that balances correctness with usability / DX, or make this configurable somehow?

But ideally, we could fix Swagger UI.

[quentinus95]

@teohhanhui Swagger UI seems to support oneOf without any issue. Here is an example, using oneOf in body definition and in a field of one of the possible bodies:

Passed schema:

openapi: '3.0.0'
info:
  title: My API
  version: 0.0.0
  description: My awesome API
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Cat'
                - $ref: '#/components/schemas/Dog'
      responses:
        '200':
          description: Updated
components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean
        breed:
          type: string
          enum: [Dingo, Husky, Retriever, Shepherd]
    Cat:
      type: object
      properties:
        hunts:
          oneOf:
            - type: string
            - type: number
        age:
          type: integer

So I think the bug should be considered to exist on API Platform side here.

[quentinus95]

@teohhanhui would a pull request fixing this issue be accepted by the API Platform core team? Or there is some uncertainty / questions you would like me to answer first before bringing a fix?

[soyuka]

I think we can fix this, note that I'm working on an OpenAPI refactor (#3407) to help us improve this part of the code

[soyuka]

#2254