如果不单独使用，nestjs/swagger 是不是支持查询参数的文档？

Posted 2023-03-10

【中文标题】如果不单独使用，nestjs/swagger 是不是支持查询参数的文档？

【英文标题】：Does nestjs/swagger support documentation of query params, if they are not used separately?如果不单独使用，nestjs/swagger 是否支持查询参数的文档？

【发布时间】：2020-04-23 07:21:44

【问题描述】：

我定义了一个路由来在我的控制器中获取订单的分页结果。

@Get()
async find(
  @Query(new ValidationPipe( whitelist: true ))
  query: OrderQueryDto & PaginatedQueryDto,
) 
  const builder = this.orderRepository
    .createQueryBuilder('order')
    .select('order.id')
    .take(query.take)
    .skip(query.skip)
    .andWhere('order.status != "deleted"');
   if (query.status) 
    builder.andWhere('order.status = :status');
  
  const [items, count] = await builder.getManyAndCount();
   return  items, count ;

但是，我想要一些关于查询参数（OrderQueryDto & PaginatedQueryDto 类型）的文档。 我没有找到任何为嵌套 swagger-module 生成的 api 描述创建文档（和测试字段）的装饰器。

我想我正在寻找类似 @ApiImplicityQueryString( type: OrderQueryDto & PaginatedQueryDto )。

我知道有一种方法可以像这样记录它：

@Get()
@ApiImplicitQuery(
  name: 'take',
  required: false,
  type: Number,
)
@ApiImplicitQuery(
  name: 'skip',
  required: false,
  type: Number,
)
// And all the other decorators for the remaining properties on OrderQueryDto [...]
async find(
  @Query(new ValidationPipe( whitelist: true ))
  query: OrderQueryDto & PaginatedQueryDto,
) 
  const builder = this.orderRepository
    .createQueryBuilder('order')
    .select('order.id')
    .take(query.take)
    .skip(query.skip)
    .andWhere('order.status != "deleted"');
  if (query.status) 
    builder.andWhere('order.status = :status');
  
  const [items, count] = await builder.getManyAndCount();
  return  items, count ;

顺便说一句，DTO 看起来像这样

import  Transform  from 'class-transformer';
import  IsInt, IsOptional  from 'class-validator';

export class PaginatedQueryDto 
  @IsInt()
  @IsOptional()
  @Transform(value => value && parseInt(value, 10))
  take?: number;

  @IsInt()
  @IsOptional()
  @Transform(value => value && parseInt(value, 10))
  skip?: number;

import  IsInt, IsOptional, IsEnum  from 'class-validator';
import  Transform  from 'class-transformer';
import  OrderStatus  from './order.entity';

export class OrderQueryDto 
  @IsInt()
  @IsOptional()
  @Transform(value => value && parseInt(value, 10))
  reseller: number;

  @IsInt()
  @IsOptional()
  @Transform(value => value && parseInt(value, 10))
  customer: number;

  @IsEnum(OrderStatus)
  @IsOptional()
  status: OrderStatus;

【参考方案1】：

在控制器中添加@ApiTags('ports')。下面的代码

控制器

import  Body, Controller, Get, Param, Post, Query  from '@nestjs/common';
import  PaginationQuery  from './pagination-query.dto';
import 
    ApiBearerAuth,
    ApiConsumes,
    ApiExtension,
    ApiHeader,
    ApiOperation,
    ApiQuery,
    ApiResponse,
    ApiSecurity,
    ApiTags
   from '@nestjs/swagger'

@ApiTags('ports')

@Controller('port')
export class PortController 
    @Get()
    findAll(@Query() paginationQuery: PaginationQuery) 

分页查询

import  ApiProperty  from '@nestjs/swagger';

export enum LettersEnum 
  A = 'A',
  B = 'B',
  C = 'C'


export class PaginationQuery 
  @ApiProperty(
    minimum: 0,
    maximum: 10000,
    title: 'Page',
    exclusiveMaximum: true,
    exclusiveMinimum: true,
    format: 'int32',
    default: 0
  )
  page: number;

  @ApiProperty(
    name: '_sortBy'
  )
  sortBy: string[];

  @ApiProperty()
  limit: number;

  @ApiProperty(
    enum: LettersEnum,
    enumName: 'LettersEnum'
  )
  enum: LettersEnum;

  @ApiProperty(
    enum: LettersEnum,
    enumName: 'LettersEnum',
    isArray: true
  )
  enumArr: LettersEnum;

  @ApiProperty()
  beforeDate: Date;

  @ApiProperty(
    type: 'object',
    additionalProperties: true
  )
  filter: Record<string, any>;

  static _OPENAPI_METADATA_FACTORY() 
    return 
      sortBy:  type: () => [String] 
    ;