Question: how to properly render query params in Swagger UI where they are represented as fields in an object?

[oliverlockwood]

I have hit an issue when trying to migrate from Swagger V2 & Springfox to OpenAPI and Springdoc. I've had a look through closed issues on this project and I think my issue is kind of the opposite of #1003.

It might just be my relative naïveté at using OpenAPI annotations, but I have spent some time experimenting with different approaches without progress, so I thought I'd raise the question here in the hope that you might be able to point me in the right direction.

Specifically:

• for simplicity and DRY principle we wrap a common (i.e. used across multiple APIs) set of query parameters into an Object, which is serialized as query params over REST and deserialized into the object on the controller layer.
• I've demonstrated the migration in an example repo: see https://github.com/oliverlockwood/demonstrate-openapi-query-param-issues/pull/1/files
• The screenshots below show what the swagger UI looks like before and after migration, for this example project.

I believe this could be worked around by use of @Parameters({@Parameter()...}) annotations on the controller method; while this would be feasible for the example project you see, it rapidly becomes unmaintainable when (as in our reality) you have ~10 query params in the common object that's used in 3 different APIs.

Before

The params are nicely listed individually, with descriptions etc. "Try it out" works as it should, as both the curl string and the correct response shows.

After

The params are only available as a block of JSON; descriptions etc are lost. This is the issue I would like to resolve. "Try it out" still works as it should, as both the curl string and the correct response shows.

[bnasslahsen]

@oliverlockwood,

This the behavior with new swagger-core/swagger-ui for OpenAPI 3.
For your case, you can simply add @ParameterObject annotation with ExampleRequest, so you can get the previous way of displaying.
More details here.

[oliverlockwood]

@bnasslahsen thank you very much indeed. Really helpful, I can confirm it works, and I'm grateful for the quick response.