Behavior when omitting content: in Open API RequestBody

[chatii]

I defined an operation using ApiResource as follows because I wanted to customize the description for the request.

// ...
new Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'I need custom description',
        ),
    ),
    input: InputPOPO::class,
),
// ...

When content: is omitted like this, the request body appears blank in the Swagger UI. To avoid this, I had to prepare an ArrayObject in content: as shown below.

    content: new \ArrayObject([
        'application/json' => [
            'schema' => [
                'type' => 'object',
                'properties' => [
                    'email' => ['type' => 'string', 'format' => 'email'],
                ]
            ],
            'example' => [
                'email' => 'user@example.com',
            ]
        ]
    ]),

As you can see, the InputPOPO class only has an $email property. Despite wanting to only rewrite the description, I have to specify verbose and extensive details.

Wouldn't it be better if, when openapi: is omitted, the class specified in input: is referenced just like "$ref": "#/components/schemas/..."? What do you think?

[monitaurus]

I've got the same issue, when I use requestBody, it makes the whole request block disappears in SwaggerUI. And we'll have to rewrite the whole content key to change the single description.

Which seems in contradiction with ApiPlatform guide:

"When a field is not specified API Platform will add the missing informations."

• Extend OpenAPI Documentation

In the OpenApiFactory, with see that the requestBody is replaced as a whole. So when said "When a field is not specified API Platform will add the missing informations." it's only for the first level keys.

If the requestBody, it would be this block that generates the default schema: https://github.com/api-platform/openapi/blob/3.1/Factory/OpenApiFactory.php#L349-L358

As rewriting the whole schema's content is complex, it would nice to have the default value system within the requestBody too.

I didn't check it, but I think a solution would be to decorate the OpenAPI Factory as menitoned in the documentation: Overriding the OpenAPI Specification.

[JoeriThissen-Simplicate]

This is a major headache for my team as well, unfortunately.

We're using API platform to create an RPC style API. Having all these automatically generated descriptions for responses and request parameters that refer to resources, makes no sense to us at all. Overriding the response description using openapi: is possible, but requires a lot of boilerplate since the whole response then needs to be defined manually. That would be somewhat fine if I could just refer to our existing DTOs when using openapi:, but even that is not supported at this time.

Sure, we could decorate the OpenApiFactory, but as far as I've seen so far, this is completely impractical if we have to specify overrides for every single API call there.

There needs to be a simple way to override defaults generated by API platform, without loosing other stuff like automatically generated response bodies, for API platform to be usable for RPC style APIs.

I'd be very interested in working on a PR to provide a fix, but at this time I don't really know where to start since I'm not very familiar with API platform internals. If anyone has any pointers, please let me know.

If we can't find a solution to this within about 2 months, it's very likely we'll have to drop API platform altogether. Shipping API documentation with lots of incorrect and confusing texts to our customers is not an option.

[monitaurus]

I gave up the overriding of the factory.
The further I progress on it, the more I felt that the default factory handles a lot of things that may have to be duplicated.

I opened a discussion here: api-platform/api-platform#2680

I hope to see it in the next discussion round of @soyuka 🤞

[soyuka]

Can't someone patch the openapi factory to set our defaults on non-existing parts of the RequestBody.

[monitaurus]

Can't someone patch the openapi factory to set our defaults on non-existing parts of the RequestBody.

@soyuka sure, I'll be glad to make a PR for that.
I already took a dive into APIP's code and spot, I think, where I can make a change.

But I was not sure if this behavior was expected or not from APIP.
That's why I open this discussion api-platform/api-platform#2680 (comment), to be sure to look on the right spot, and doing the right thing.