NestJS结合Swagger使用@ApiQuery时如何声明查询参数默认值？

@ApiQuery完全支持配置查询参数默认值并在Swagger文档中展示，以下是两种常用实现方案：

方案1：单独使用@ApiQuery装饰器（适合参数少的场景） #

你当前写的代码本身就是可运行的正确写法：

@Get()
@ApiQuery({name: 'page', default: 1, type: Number})
@ApiQuery({name: 'limit', default: 5, type: Number})
async getDocuments(
  @Query('page') page: Number = 1, 
  @Query('limit') limit: Number = 5
){
  return this.documentsService.getDocuments(page, limit);
}

• 只要你的项目依赖@nestjs/swagger版本≥4.0，该配置会自动生效
• 启动项目后打开Swagger页面，对应接口的参数列表会直接展示page默认值为1、limit默认值为5，调用接口时未传参的情况下Swagger会自动填充默认值发起请求

方案2：基于DTO统一配置（适合参数多、需要参数校验的场景） #

也就是评论区提到的实现方案，更便于参数的统一维护，同时支持参数校验、自动类型转换能力：

第一步：定义分页查询DTO类 #

import { ApiProperty } from '@nestjs/swagger';
import { IsOptional, IsNumber } from 'class-validator';
import { Type } from 'class-transformer';

export class PageQueryDto {
  @ApiProperty({ description: '查询页码', default: 1, type: Number })
  @IsOptional()
  @IsNumber()
  @Type(() => Number)
  page: number = 1;

  @ApiProperty({ description: '每页返回数据条数', default: 5, type: Number })
  @IsOptional()
  @IsNumber()
  @Type(() => Number)
  limit: number = 5;
}

第二步：接口中使用DTO接收参数 #

@Get()
async getDocuments(
  @Query() query: PageQueryDto
){
  return this.documentsService.getDocuments(query.page, query.limit);
}

• 该写法无需额外添加@ApiQuery装饰器，Swagger会自动读取DTO中@ApiProperty的配置生成参数说明，默认值也会正常展示
• 配合class-validator和class-transformer可以自动完成参数的类型转换、合法性校验，无需手动处理参数格式

内容的提问来源于stack exchange，提问作者Cris