[REQ] for Spring Projects possibility of pack query string in a class

[juniorjrjl]

Hello, I would suggest this issue for avoid to declare many query strings in method. In Spring is possible transform a methods like this:

// each query string like a method parameter
@GetMapping
public ResponseEntity<SampleResponse> filter(int page, int size, String sort, String direction){ 

}

in this method with a class with params

// SampleParam class contains all properties used in prior code: int page, int size, String sort, String direction
@GetMapping
public ResponseEntity<SampleResponse> filter(SampleParam params){ 

}

Spring provide class for build endpoints with many queryString params ( ex.: pagable responses), also we can split params in more class, ex.:

import org.springframework.data.domain.Pageable;

//Pageable is a Spring interface who pack page params (page, size, direction, sort)
//SampleParam could be contains params used for filter results( ex.: filter by name, date, isActive, etc.)
@GetMapping
public ResponseEntity<SampleResponse> filter(SampleParam params, Pageable pageable){ 

}

another detail, a pageable spring interface use annotations to configure default values when user don't send nothing, ex.:

// annotations define some default values used by pageable implementation provided by spring
@GetMapping
public ResponseEntity<SampleResponse> filter(
@PageableDefault(size = 20) 
    @SortDefault.SortDefaults({
        @SortDefault(sort = "status", direction = Sort.Direction.DESC),
        @SortDefault(sort = "nome", direction = Sort.Direction.ASC)
    })
Pageable pageable){ 

}

it's is very helpfull for avoid to have a method with many arguments, could have a some param for do this in openapi,yml (ex.: x-class-query-string-pack), ex:

parameters:
    - name: size
       in: query
       x-class-query-string-pack: org.springframework.data.domain.Pageable # refer to spring interface
       x-class-query-string-annotation: @PageableDefault(size = 20)  # to input annotation in spring object
    - name: page
       in: query
       x-class-query-string-pack: org.springframework.data.domain.Pageable # refer to spring interface
#other params ....
    - name: isActive
       in: query
       x-class-query-string-pack: SampleParam # could be a class name used to create a custom pack class
      # for custom class dont need annotation, is possible define default, if have using contructor, prop init value
    - name: startDate
       in: query
       x-class-query-string-pack: SampleParam # could be a class name used to create a custom pack class
#other params ....

and this config could generate a method with a class/classes pack a query string params

[Picazsoo]

I would personally strongly recommend against trying to do this via vendor extensions. Vendor extensions are great, when you are the owner of the API spec. But as soon as you become a consumer of someone else's spec, then the vendor extensions become kind of a nuisance.

IMO better is to have some support via configOptions.

But maybe this is basically usable only for a controller and hence one can be reasonably expected to be the API spec owner??

And for Pageable there is already support in java-spring and kotlin-spring. Including the defaults. Mind you there is a couple of bugs to iron out, but both default page/size and default sort params can now succesfully generate annotations for the Pageable. Look into the generators' documentation or the samples included in the source code.

But a generic possibility to wrap many params into a custom multi-param object sounds interesting.

These are just my 2 cents.

[juniorjrjl]

@Picazsoo thank you for comment, it's could be good to improve a possible new feature. I started to use open api in my work and I like it. :)

[juniorjrjl]

@Picazsoo thinking more about the feature and considering your opinion I have a idea to simplify this possible feature.

Could be a configuration in configOptions ( for example):

<configOptions>
        <packQueryString>true</packQueryString>
</configOptions>

for class name could use a method name with suffix "param" ex.: method = filterCompany, packClass = FilterCompanyParam. If a queryString params match with spring page interface use it and for other params create a new class.

[juniorjrjl]

Another alternative for this issue could be create a configOptions like

<configOptions> <packQueryStringMinAmount>3</packQueryStringMinAmount> </configOptions>

with default value o, if you define, for example 3, all methods who have 3 queryStrings or more packing params in a class, another advantage for packing besides the verbosity reduce is about bean validation compare queryString fields, ex. if have startDate and EndDate check if endDate Is greater than Start date using a custom validator

[juniorjrjl]

@Picazsoo what do you think about this issue follow a option to use config ( like I said in before post, saying amount of args is packing in class)? I'll organize suggests in one comment explain better about the suggest

[lcf2014]

Following issue

[Picazsoo]

This is IMO a valid proposal. I am just a regular contributor here, not a maintainer. As for my capacity to implement this - I am currently working through some open issues (bugfixes mostly), and once those are wrapped up I will probably be stepping away from the project for a bit to recharge. So I will not be picking this up myself.

But if anyone in the community would like to take it on, I expect a PR would be very welcome!

[juniorjrjl]

Awesome! I will put all details here to help a developer with information:

Proposal

Possibility to packing queryString params in a class, ex.:

this endpoint:

@GetMapping
public ResponseEntity<SampleResponse> filter(final int page, final int size, final String sort, final String direction){ 

}

could be

@GetMapping
public ResponseEntity<SampleResponse> filter(SampleParam params){ 

}

Advantages

• Less verbosity;
• Possibility to apply more customizations in bean validation, ex.:

when we using many params in method we just only validate a isolated value, but when we packing all in a class we can validate values together:

@Period// custom annotation to check if querystring dates is a valid range
public class SampleParam{
    @Period.Begin // to mark start date
    private OffsetDateTime startAt;
    @Period.End // to mark end date
    private OffsetDateTime endAt
//getters and setters
}

More Details

For implement this option could create a config

<configOptions>
    <packQueryStringMinAmount>3</packQueryStringMinAmount> // methods with 3 or more queryStrings will receive a class with packed params
</configOptions>

for using bean validation we can use a existing vendor extensions:
x-field-extra-annotation
x-class-extra-annotaion
x-items-extra-annotation ( waiting PR approve here: #23710)

If possible, using a Spring provided class for pagination, a Pageable class if a queryString names match with Pageable params and using another custom class to packing another params, ex.:

@GetMapping
public ResponseEntity<SampleResponse> filter(final Pageable pageable /*packing pagination params*/, final SampleParam params /*packing another params*/){ 

}

for set default values in custom class:

public class SampleParam{
    private boolean active = true; // when openapi define default values to queryString
//getters and setters
}

for spring Pageable:

@GetMapping
public ResponseEntity<SampleResponse> filter(
@PageableDefault(size = 20) 
    @SortDefault.SortDefaults({
        @SortDefault(sort = "status", direction = Sort.Direction.DESC),
        @SortDefault(sort = "nome", direction = Sort.Direction.ASC)
    }) // using to set default values in spring class 'Pageable'
Pageable pageable){ 

}

but if not possible use spring Pageable, its ok create a custom class to packing all

[Mattias-Sehlstedt]

Hi,

First of all I would like to suggest to use markdown to get syntax highlighting for code blocks. It makes it much easier for a human to parse and understand the examples.

For the reported issue, is there any reason why the specification would not define objects in the query to achieve this? That would make the specification and the controller align to each other and express the exact same thing, rather than the specification being flat and then that some extremely complex config logic would have to attempt to interpret lists of query parameters and try to join them into objects.

Example of such a query:

openapi: 3.0.3
info:
  title: test
  version: 1.0.0
paths:
  /test:
    get:
      operationId: test
      parameters:
        - name: inputOptions
          in: query
          required: false
          style: form
          schema:
            $ref: '#/components/schemas/Options'
          explode: true
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    Options:
      type: object
      properties:
        a:
          type: string
          format: date-time
        b:
          type: string
          format: date-time
        c:
          type: array
          items:
            type: string

[juniorjrjl]

@Mattias-Sehlstedt thank you about tip to use syntax highlighting, I edited previews comment.

About the your suggests, I did't say about pass object in query String, I saying about a spring particularity. ex.:

In openapi we could have a follow endpoint:

  /api/v1/products:
    get:
      tags:
        - Products
      parameters:
        - schema:
            type: string
            example: Notebook Gamer
          in: query
          name: term
          description: Search term for multiple fields, like name, description, brand.
          required: false
        - schema:
            type: boolean
            example: true
          in: query
          name: hasDiscount
          description: Products with discount
          required: false
        - schema:
            type: boolean
            example: true
          in: query
          name: enabled
          description: Only enabled products or disabled
          required: false
        - schema:
            type: boolean
            example: true
          in: query
          name: inStock
          description: Only products in stock or out of stock
          required: false
        - schema:
            type: number
            example: 100.99
          in: query
          name: priceFrom
          description: Minimum price
          required: false
        - schema:
            type: number
            example: 100.99
          in: query
          name: priceTo
          description: Maximum price
          required: false
        - schema:
            type: string
            example: "9e965c97-93c2-4d71-970f-0e8bf24ba0fb"
          in: query
          name: categoriesId
          description: Categories id
          required: false
        - schema:
            type: string
            format: yyyy-mm-dd
            example: "2024-09-01"
          in: query
          name: addedAtFrom
          description: Initial product creation date
        - schema:
            type: string
            format: yyyy-mm-dd
            example: "2024-09-01"
          in: query

is possible to create endpoint with spring using two options ( issue suggest):

1) packing al queryString in method:

@GetMapping("/api/v1/products")
public List<ProductResponse> findProducts(
        @Valid ProductFilter filter
) {
    ...
}

public record ProductFilter(

        String term,

        Boolean hasDiscount,

        Boolean enabled,

        Boolean inStock,

        BigDecimal priceFrom,

        BigDecimal priceTo,

        UUID categoriesId,

        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
        LocalDate addedAtFrom,

        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
        LocalDate addedAtTo
) {
}

using this way we have a advantages I said before.

2) receive all params on method ( like pluging generate until now):

@GetMapping("/api/v1/products")
public List<ProductResponse> findProducts(

        @RequestParam(required = false)
        String term,

        @RequestParam(required = false)
        Boolean hasDiscount,

        @RequestParam(required = false)
        Boolean enabled,

        @RequestParam(required = false)
        Boolean inStock,

        @RequestParam(required = false)
        BigDecimal priceFrom,

        @RequestParam(required = false)
        BigDecimal priceTo,

        @RequestParam(required = false)
        UUID categoriesId,

        @RequestParam(required = false)
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
        LocalDate addedAtFrom,

        @RequestParam(required = false)
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
        LocalDate addedAtTo

) {
    ...
}

is not about openapi representation, but about configure how plugin will generate the code, my suggest is about to create a new config to possibility to using a first approach already supported by spring to receive queryString

[Mattias-Sehlstedt]

If you use the query definition that I suggest, then you should be able to get

@Get("/test")
public void test(Options inputOptions) {
   ...
}

I.e., if you state that some fields are related in the specification with objects in the query, then the generator will utilize those objects in the controller signature too. And to my understanding that is exactly what we want to achieve? We want to relate query parameters to each other and be able to capture them in wrappers so that the controller signature is shorter. E.g.,

components:
  schemas:
    ProductFilter:
      type: object
      properties:
        term:
          type: string
        hasDiscount:
          type: boolean
        enabled:
          type: boolean

[juniorjrjl]

@Mattias-Sehlstedt Thank you :), I try hera and works well following your suggests, and about use Spring interface Pageable in situations where params is match and remain params is allocated to another object, it's possible add this feature? You solve my problem, this suggest is desirable

[Picazsoo]

Hi @juniorjrjl,

@Mattias-Sehlstedt's approach probably really covers your use case. Since this is controller generation (where you supposedly own the spec), it's the cleaner path: model the related params as an object query parameter with explode: true. The wire format stays flat (?startAt=...&endAt=...), but Spring binds it as a command object.

Two key points:

1. @Valid is generated automatically on the object param (java + spring, useBeanValidation on by default), so cross-field validation fires.
2. You can probably mix in validation via an interface using x-implements, avoiding repeated annotations. Field constraints go on the interface getters (interfaces have no fields).

paths:
  /products:
    get:
      operationId: findProducts
      parameters:
        - name: filter
          in: query
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/ProductFilter'
components:
  schemas:
    ProductFilter:
      type: object
      x-implements:
        - com.example.PeriodRange
      properties:
        startAt: { type: string, format: date-time }
        endAt:   { type: string, format: date-time }

// hand-written, reusable
@Period
public interface PeriodRange {
    @Period.Begin OffsetDateTime getStartAt();
    @Period.End   OffsetDateTime getEndAt();
}

This generates findProducts(@Valid ProductFilter filter), where ProductFilter implements PeriodRange, and Bean Validation considers the constraints declared on the interface methods when validating the implementing class. So you get the packed signature plus cross-field validation today, no new config needed.

If you'd rather keep the interface wiring out of the spec entirely, you can add it directly via the schemaImplements config option instead of x-implements, e.g. schemaImplements: {ProductFilter: com.example.PeriodRange}. It's fully decoupled from the API spec.

For the pagination part, x-spring-paginated injects a Spring Pageable (handling page/size/sort), and there are dedicated options for its defaults and validation:

• autoXSpringPaginated automatically applies x-spring-paginated to any operation that has page, size, and sort query parameters, so you don't have to annotate each operation manually.
• generateSortValidation generates a @ValidSort annotation + SortValidator and applies it to the injected Pageable when the sort parameter has enum values, validating sort values against the allowed spec values.
• generatePageableConstraintValidation generates a @ValidPageable annotation + PageableConstraintValidator and applies it to the injected Pageable to enforce page/size maximum constraints from the spec.

Both validation options require useBeanValidation=true and library=spring-boot. Defaults for page/size/sort declared in the spec are picked up when generating the Pageable support.

The defaults don't work perfectly yet when inheriting: since OpenAPI doesn't specify precedence for conflicting defaults across composed schemas (allOf, etc.), the resolved default can be ambiguous. And I expect you might run into more instances where these defaults will not appear as expected...

[juniorjrjl]

Hello @Picazsoo , so I'll close this issue. thank you for help. This was the most annoying problem and it's solved :)