[FEAT] OAS3 — allow to configure serialization attributes for query parameters

[denis-maiorov-brightsec]

Information

Is your feature request related to a problem? Please describe.
Swagger UI allows to "try" endpoints. It then composes url based on serialization rules. At the moment there is no way to configure these rules. They do not align with platform-express deserialization well. In most cases it works but query object parameters require deepObject style.

Describe the solution you'd like
As deserialization is usually depends on platform and/or configured globally, the solution is to set serialization attributes(style, explode) for query parameters on global level.

const swaggerConfig: SwaggerOS3Settings = {
   // ...
   parameterSerialization: {
      query: {
         // key in OpenSpecTypes
         object: {
            style: 'deepObject',
            explode: true
         }
      }
   }
}

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Acceptance criteria

• Criteria 1

[Romakita]

Hello @denis-maiorov-brightsec

In fact you can configure any global settings through the swagger.*.spec option:

{
   "swagger": [
      {
         "path": "/doc",
         "spec": {
            "parameterSerialization": {
              "query": {
                // key in OpenSpecTypes
                 "object": {
                   "style": "deepObject",
                   "explode": true
                 }
              }
            }
         }
      }
   ]
}

See you
Romain

[Romakita]

Making PR to add typing is also possible:
https://github.com/tsedio/tsed/blob/production/packages/specs/openspec/src/openspec3/OpenSpec3.ts

[denis-maiorov-brightsec]

Hello @denis-maiorov-brightsec

In fact you can configure any global settings through the swagger.*.spec option:

{
   "swagger": [
      {
         "path": "/doc",
         "spec": {
            "parameterSerialization": {
              "query": {
                // key in OpenSpecTypes
                 "object": {
                   "style": "deepObject",
                   "explode": true
                 }
              }
            }
         }
      }
   ]
}

See you Romain

Thanks for having a look!

The problem is that there's no such global option in Swagger 😢. Those style and explode property should be set individually for each parameter.
Parameters can be defined in components and then referenced in operations but Tsed does not support that as well, and honestly I don't think it's much useful for the issue described.

[Romakita]

Ok I see. Yes, Ts.ED support deep query parameters and the style: deepObject is automatically enabled is you use a model on query. See more here:
https://tsed.io/docs/model.html#deep-object-on-query

[denis-maiorov-brightsec]

@Romakita ah, I see. The problem then is that It's not working when QueryParams is used like this:

@Generics('T')
export class QueryParamBetweenFilter<T> {
  @Description('Greater than constraint')
  @Property('T')
  public gt?: T;

  @Description('Greater than or equal constraint')
  @Property('T')
  public gte?: T;

  @Description('Less than constraint')
  @Property('T')
  public lt?: T;

  @Description('Less than or equal constraint')
  @Property('T')
  public lte?: T;
}

export class Filters {
  @GenericOf(number().integer())
  public param?: QueryParamBetweenFilter<number>;

}

@Controller({path: '/test'})
class TestDeepObjectCtrl {
  @Get('/works')
  public get(@QueryParams("param") @GenericOf(number().integer()) q: QueryParamBetweenFilter<number>) {

  }

  @Get('/doesNotWork')
  public get(@QueryParams() filters: Filters) {

  }
}

[Romakita]

it's probably a missing usecase in @tsed/schema ^^

[denis-maiorov-brightsec]

@Romakita seems like I should close this issue and open a bug issue then?

[Romakita]

Yes if you have a time. Keep this issue open also.
We will see later if we need to close it ;)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Romakita]

#2309