Hi Mattias, first of all thank you for answering . I understand that ModelAttribute is not supported, that's unfortunate. So the only way to actually have query params on my REST APIs is to add all the fields in the RestController methods with the RequestParam annotation, right ?

Changing the TOs has an impact on external systems over which I have no control, so I cannot make any changes on these classes for now. That's why I was looking for a way to add the metadata I need for documentation directly on RestController

Also, just out of curiosity of how others manage their openapi contracts, how would introducing additional TOs affect external consumers? Do they automatically pull your specification and attempt to generate a client based upon it? Because technically you changing your specification should not affect anything as long as your service offers the same functionality. E.g., you could rename a model or add new fields, but as long as your service still accepts the json/query structure that is serialized based on the code they use for your old specification, then there is no issue.

The only issue might be that they get annoyed that their generated client changes a little bit now and then, but if you can motivate why it is important, then they should mostly be happy that the specification they have access to better expresses what it actually offers and does.

It's a long story but basically yeah, there is an old GWT (yes, Google Web Toolkit) project that is based on these TOs. It is an old Java 8 projects but the Spring project is on Java 21 so almost every new line of code could break everything and it happened too many times already.

Talking about the meta-annotation solution you suggested, I checked that in swagger there is already an annotation aggregator for @parameter called @parameters , so I tried adding multiple @parameter annotations on my method to describe the query parameters and it works. The problem is that I also get the TOs as one of the possible query parameters.
Do you think I can fix that the way I want it ?

openapi: 3.0.1
info:
 title: OpenAPI definition
 version: v0
servers:
- url: http://localhost:8080
 description: Generated server url
paths:
 /product:
 get:
 tags:
 - product-controller
 operationId: getProductTOsByFilter
 parameters:
 - name: filter
 in: query
 required: true
 schema:
 $ref: "#/components/schemas/ProductTO"
 - name: productID
 in: query
 required: true
 schema:
 type: string
 example: "0001"
 - name: productName
 in: query
 schema:
 type: string
 example: My Product
 responses:
 "200":
 description: OK
 content:
 '*/*':
 schema:
 type: array
 items:
 $ref: "#/components/schemas/ProductTO"
components:
 schemas:
 ProductTO:
 type: object
 properties:
 productID:
 type: string
 productName:
 type: string
 weight:
 type: number
 format: float
 description:
 type: string

You could try and see if ...(@ModelAttribute @Schema(hidden = true) ProductTO filter)... would properly hide it in the specification

It worked !
thanks a bunch for all the help, Mattias
Couldn't make it without your knowledge