[feature] @OA\RequestBody, but for "query"

[arjanfrans]

Version
I am using version 4.0@dev.

Problem
I define all my request parameters in a "Model" class. By using the @OA\RequestBody annotation I get my parameters documented automatically. This works great for all POST/PATCH/PUT requests that have a body. For GET requests I also like to define my parameters in a Model class.

As a "workaround" to document the endpoints I put "query" in the description. However, I can then not use the "Try it out" feature. Here is my implementation:

Feature
What I'd like to see is an @OA\RequestBody annotation for query parameters (@OA\RequestQuery?) so that I can define my query parameters in my Model class.

My Model classes contains the types and validations, one place where everything is defined. I don't want to define OA\Parameter annotations on my route too.

[GuilhemN]

This is actually supported using openapi 3 features, please see #1596 (comment).

In summary, you should use an usual @Parameter with @Model and the explode field.

[GuilhemN]

Closing as fixed, feel free to reopen if this is not the case.

[Luehrsen]

Does anybody have a working implementation for this?

Currently doing

     * @OA\Parameter(
     *   name="query",
     *   in="query",
     *   style="form",
     *   explode=false,
     *   @OA\Schema(
     *     ref=@Model(type=CharacterFilter::class, groups={"read"})
     *   )
     * )

and getting

Side question: Does the bundle pick up parameters that are in traits? Edit: Anwser, yes! But those seem to be cached, so you have to clear caches to make them visible in the doc.

[PetrNovotnyGS]

Does anybody have a working implementation for this?

Currently doing

     * @OA\Parameter(
     *   name="query",
     *   in="query",
     *   style="form",
     *   explode=false,
     *   @OA\Schema(
     *     ref=@Model(type=CharacterFilter::class, groups={"read"})
     *   )
     * )

and getting

Side question: Does the bundle pick up parameters that are in traits? Edit: Anwser, yes! But those seem to be cached, so you have to clear caches to make them visible in the doc.

Unfortunatelly not:(

Currently using this workaround

But it would be perfect, if
new OAT\Parameter(name: 'query', in: 'query', explode: true, schema: new OAT\Schema(ref: new Model(type: AccountFilter::class))

would generate working doc like this

[chrisguitarguy]

y'all probably want style="form" and explode=true to get the example you want. I see style="form" with explode=false in the examples above.

[PetrNovotnyGS]

Tried almost everything, but without success. My code is:

Result is:

[chrisguitarguy]

can you try new OAT\Parameter(in: "query", name: "query", style: "form", explode: true, ref: new Model(....))?

Basically remove the schema bit and put the ref directly into the parameter.

[PetrNovotnyGS]

new OAT\Parameter(name: 'query', in: 'query', ref: new Model(type: AccountFilterDTO::class), style: 'form', explode: true)
results in "mb_substr(): Argument #1 ($string) must be of type string, Nelmio\ApiDocBundle\Annotation\Model given"

when used through alias
new OAT\Parameter(name: 'query', in: 'query', ref: '#/components/schemas/AccountFilter', style: 'form', explode: true)
doc is working, but parameters are empty.

[prugala]

@PetrNovotnyGS or someone else, do you have a solution maybe?

[simmstein]

Same issue. Have you a solution?

[adamgregory]

@GuilhemN @chrisguitarguy
any chance we can reopen this issue because the issue in #1721 (comment) is not fixed?

[Luehrsen]

So I've spent some time going down the rabbithole of this issue:

By all accounts, the feature requested here is not possible at the moment. This is also not a bug, but rather a limitation of the OpenApi specification. That means the issue is waaaay upstream.

This has also been discussed in the swagger-php repository, e.g. in zircote/swagger-php#663 with limited solutions.

One possible solution would be to augment the doc-generation with a custom parameter, that transforms the parameters of the referenced model the way we want. An example can be found here: https://github.com/zircote/swagger-php/pull/783/files

The downside of this solution is the fact, that swagger-php can theoretically register custom processors, but the NelmioApiDocBundle can not.

So my proposed solution would be to allow exactly that: Custom processors through the yml config. I'll open a feature request for that.

[Luehrsen]

Resolving this is now possible with #2149 and has been released in v4.14.0. You'll need a custom processor to do that. This is roughly how you do it:

1. Generate a custom process as per the official swagger-php examples in your symfony app.
2. Register the processor with the tag nelmio_api_doc.swagger.processor as described here.
3. The custom processor is now used in the generator.

Note: You can influence WHEN the processor is run by giving the tag a before attribute. The attribute takes the FQN of an existing processor and adds your custom processor right before it.