Complete missing OpenAPI informations for other model object than operation

[monitaurus]

Hi, I tried to change the OpenAPI description of a request's body with this code:

#[ApiResource(
    operations: [
        new Post(
            uriTemplate: '/test',
            input: TestPayload::class,
            output: false,
            openapi: new Operation(
                summary: 'Summary of the operation.',
                description: 'Description of the operation.',
                tags: ['Operation'],
                responses: [
                    '204' => new Response(description: 'Response description.'),
                ],
                requestBody: new RequestBody(
                    description: 'Request body.',
                    required: true,
                ),
            ),
        ),

Within the openapi.json, the requestBody appears, without content. In the UI, the whole blank is blank. I think that's an issue related to SwaggerUI.

But this lead me to find out that this guide page Extend OpenAPI Documentation saying :

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

It's true, but only for fields directly within Model\Operation constructor.

By looking at the OpenApiFactory code, see L396-L408, if there's no RequestBody within openapi: it generates the whole default object.

Then, if in openapi: we just want to edit the description with a new RequestBody(description: "Another description"), and then we'll end up with a request body with no content:.

The issue, is that generating OpenAPI content it pretty complex depending on the size of the resource. Moreover there are several schemas to specify if we have several formats available, like json or jsonld. It breaks the powerful automation of API Platform around the documentation

I think that something could be done by decorating the factory, but I'm not at ease with the factory, and it seems there are many things to be done to gather informations to generate the schema, etc ...

💡 I'll be glad to discuss the possibility to bring the "add the missing information" from the docs, to sub part of the OpenAPI model object, and if I can help to do so.

Related discussion I found:

• https://github.com/api-platform/api-platform/issues/2567
• Response description is not changable when using openapi core#5381

[JoeriThissen-Simplicate]

I'm going to shamelessly copy & paste my response from another discussion here :)

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.