NestJS如何实现嵌套对象作为查询参数并生成OpenApi文档？

这个需求在NestJS中完全可行，当前Swagger文档显示异常的问题主要出在类导出方式、Swagger配置及参数转换的全局配置上，以下是具体解决方案：

问题分析 #

1. 默认导出（export default）会导致Swagger无法正确识别嵌套类型的引用关系；
2. 未明确配置Swagger嵌套对象的Schema结构，导致文档展示不符合预期；
3. 全局ValidationPipe未启用参数转换，无法将URL中的createdAt[startDate]格式解析为嵌套对象。

修正后的代码实现 #

1. 调整日期筛选类（命名导出+完善装饰器） #

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

export class DateFiltersInput {
  @ApiProperty({ required: false, description: '起始时间戳' })
  @IsNumber()
  @Expose()
  @IsOptional()
  startDate?: number;

  @ApiProperty({ required: false, description: '结束时间戳' })
  @IsNumber()
  @Expose()
  @IsOptional()
  endDate?: number;
}

2. 调整查询参数类（明确Swagger嵌套结构） #

import { ApiProperty } from '@nestjs/swagger';
import { IsNumber, IsOptional, ValidateNested } from 'class-validator';
import { Type } from 'class-transformer';
import { DateFiltersInput } from './date-filters.input';

export class GetContentsQuery {
  @ApiProperty({ required: false, description: '创建者ID' })
  @IsNumber()
  @IsOptional()
  createdBy?: number;

  @ApiProperty({
    required: false,
    description: '创建时间范围',
    type: DateFiltersInput,
    schema: {
      type: 'object',
      properties: {
        startDate: { type: 'number' },
        endDate: { type: 'number' }
      }
    }
  })
  @IsOptional()
  @Type(() => DateFiltersInput)
  @ValidateNested()
  @Expose()
  createdAt?: DateFiltersInput;

  @ApiProperty({
    required: false,
    description: '更新时间范围',
    type: DateFiltersInput,
    schema: {
      type: 'object',
      properties: {
        startDate: { type: 'number' },
        endDate: { type: 'number' }
      }
    }
  })
  @IsOptional()
  @Type(() => DateFiltersInput)
  @ValidateNested()
  @Expose()
  updatedAt?: DateFiltersInput;
}

3. 全局ValidationPipe配置（启用参数转换） #

在main.ts中配置全局管道，确保NestJS能自动将URL中的嵌套查询参数转换为对象结构：

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 启用全局验证管道，开启参数转换
  app.useGlobalPipes(new ValidationPipe({
    transform: true,
    transformOptions: {
      enableImplicitConversion: true,
    },
    whitelist: true, // 自动过滤未定义的字段
  }));

  // 配置Swagger文档
  const swaggerConfig = new DocumentBuilder()
    .setTitle('内容管理API')
    .setDescription('支持嵌套日期筛选的内容查询接口')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, swaggerConfig);
  SwaggerModule.setup('api-docs', app, document);

  await app.listen(3000);
}
bootstrap();

验证效果 #

启动服务后访问/api-docs，Swagger文档会正确展示createdAt和updatedAt的嵌套字段；发送示例请求GET /contents?createdBy=1&createdAt[startDate]=1234&createdAt[endDate]=1235&updatedAt[startDate]=5678&updatedAt[endDate]=5679，后端会自动解析为你期望的嵌套对象结构。

内容的提问来源于stack exchange，提问作者Sévrain CHEA