Swagger: Automatically detect optional @Query

[mjgp2]

Am I right in thinking that you could look for a ? on the query function parameter to denote that it is optional, and pick this up to set the required value on the swagger document?

It would be nicer than having to add decorators like @ApiImplicitQuery({name:'offset',required:false}) to the method I think. What do you reckon?

Thanks :)

[alisherks]

One option will be to use a class as your query parameters:

class MyParams {
  @ApiModelProperty()
  prop: number;
  @ApiModelPropertyOptional()
  optionalProp: number;
}

@Controller('MyCtrl')
class MyCtrl {
  @Get()
  async getList(@Query() params: MyParams) {
    ...
  }
}

[mjgp2]

Sure, good idea, but I would still rather have something where the API properties can be inferred by reflection rather than more decorators as it becomes much more verbose 👍

[jaufgang]

Keep in mind that a param could also be optional if it has a default value rather than a ?. For example:

@Controller("transactions")
export class TransactionsController {

    @ApiImplicitQuery({
        name: "limit",
        description: "The maximum number of transactions to return",
        required: false,
        type: Number
    })
    @Get("recent")
    getRecentTransactions(@Query("limit", new ToIntPipe()) limit: Number = 10) {
        ...
    }
}

It would be ideal if swagger could detect the default value using reflection and document that the param is optional as well as the default values.

Also, note that in this example the param type is explicitly declared as Number, but this is also not reflected in the swagger docs if we omit the @ApiImplicitQuery({type: Number}). In fact, the _try it out_ form field will currently not accept a number without the type specified in the ApiImplicitQuery decorator.

It would be ideal if all of these things could be inferred by reflection so that you would only need to use the @ApiImplicitQuery decorator to add the description.

[cristiboariu]

@jaufgang + 1

[kvgros]

+1

[kamilmysliwiec]

Reflection doesn't give us any information about optionals/default values. We'd have to use a new script that makes use of AST to properly indicate whether something is required or not.

[kunokdev]

So how do we define optional param?

[jaufgang]

@kunokdev, you specify an optional param by setting required: false in the @ApiImplicitQuery decorator. (see my sample code above)

[kamilmysliwiec]

The plugin released in version 4.0.0 will automatically detect optional properties in your class https://docs.nestjs.com/recipes/swagger. However, it still doesn't check controller's methods signature (something to add in the future).

[prinzdezibel]

[..]
getRecentTransactions(@Query("limit", new ToIntPipe()) limit: Number = 10) {
[..]

You mentioned the custom pipe ToIntPipe. Does this mean the Nest.js framework does not come up with a out-of-the-box solution for this trivial example (an optional query parameter)?

While it wouldn't be a big deal to write a custom pipe that doesn't throw (as opposed to ParseIntPipe), I'm inclined to think that I'm missing something here. Any thoughts, @jaufgang ?

[mareksuscak]

@prinzdezibel and everyone else looking for a solution — there is a documented way to chain multiple pipes where one of them can inject a default value. The DefaultValue pipe must precede ParseIntType or whatever other pipe you're using. Here's a direct link to the section that documents this: https://docs.nestjs.com/pipes#providing-defaults

But it's true that it took me a while to find it.

[nartc]

Thanks @mareksuscak. Closing

[mjgp2]

@nartc - that's not actually the answer to the original question, I don't think you should have closed it :)

I think as @kamilmysliwiec says, "it still doesn't check controller's methods signature (something to add in the future)."

[murbanowicz]

@kamilmysliwiec does reopening means that is being worked on?

[tamtakoe]

Maybe to add OptionalPipe for Swagger?

But the best way of course to use ?

getData(@Query('limit') limit?: number)

[jameskuizon13]

@tamtakoe It doesn't work for me.

[tamtakoe]

@jameskuizon1315 It doesn't work. It was an idea for contributors