Add QueryString documentation when using TransferObject with @ModelAttribute as single argument

[angelomarzocchi]

I'd like to add OpenAPI documentation to my project but I have the following problem :
I have a lot of RestController where th eonly input of the methods is a TransferObject with the @ModelAttribute annotation to map each field of the Transfer Object as a query parameter. In my real life scenario not every field is used for every request, so I would like to add some sort of documentation to specify which fields are used .
I have no idea how to achieve this result, can someone help ?
I'd like to add annotation to the RestController class, leaving the TO as it is.
Here I have an example of what I have in my project : https://github.com/angelomarzocchi/springdocdemo
And this is the documentation I have right now :

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"
     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

The result I want is to have productID and productName as parameters in the yml documentation.
Something like :

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: productID
       in: query
       required: false
     - name: productName
      in: query
      required: false
     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

Thank you everyone in advance

[Mattias-Sehlstedt]

It seems to have been discussed before and then it was a no #119 (and a second time more recently #2439).

I'd like to add annotation to the RestController class, leaving the TO as it is

Could we elaborate on this reasoning? Personally I would like the api-object itself to describe what expectations it has on data (i.e., whether it is required or not), so I would most likely create several different ProductXTO to describe the different permutations of required field combinations that can exists (this is of course not viable if ProductTO in reality has many more fields than 4).

[angelomarzocchi]

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

[Mattias-Sehlstedt]

I believe a possible approach could be to introduce a meta-annotation similar to the one introduced here, and then make it carry a number of annotations that describe the query parameters that you have (and you could probably make the annotation take an argument, so you could controller the required value for each annotation?).

The annotation that I am thinking of would be:

@Parameter(name = "queryValue", in = ParameterIn.QUERY, example = "1", schema = @Schema(type = "number"))

from swagger annotations.

[Mattias-Sehlstedt]

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.

[angelomarzocchi]

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

[Mattias-Sehlstedt]

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

[angelomarzocchi]

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