nest中常用的swagger写法

nest使用中,除了在DTO中使用class-validator去做校验。

还可以去写swagger文档。

nestcontroller写法中,代码如下

//person.controller.ts

@Post()
async create(@Body() person: PersonDTO): Promise {
  return  ....
}

SwaggerModule会查找到@Body这个装饰器来生成API文档。同样的装饰器还有@Query,@Param。至于详尽的api说明都是从PersonDTO中解析出来。

可以查阅中文文档链接

下面是一些常用的装饰器

ApiProperty

参数说明

  • type 类型
  • required 是否必须
  • description 描述
  • default 默认值
  • name 属性名称,默认是装饰器修饰的属性名,但是显性的设置name文档中按照这个name的value为最终输入值

type

DTO的写法

class PersonDTO {
  name: string;
  
  app: number; //或者
  
  links: string[]// 数组 
  
}

这是ts的写法

而ApiProperty支持的TypeString,Number,Function,以及数组[String]

数组的写法就是这样,一定要在type属性声明为[type]或者设置isArray属性为true

ApiBody

TypeScript 不会存储有关泛型或接口的元数据.

需要使用ApiBody显性设置类型。

对于没用参数装饰器三兄弟的,又需要写文档的,就用ApiBody制定一个DTO

@ApiBody({ type: [CreateUserDto] })
createBulk(@Body() usersDto: CreateUserDto[])

设置可选 ApiPropertyOptional

ApiProperty默认是必填的,如果期望是选填的。

可以使用ApiPropertyOptional来代替。可以不需要去{required: false}

ApiPropertyOptional其它参数参考ApiProperty.

返回可选的装饰器 PartialType()

对于create操作,所有的参数可能都是必填。

而对于update操作,只需要更新部分操作。

通过PartialType可以返回一个所有输入都是可选的参数

export class UpdatePersonDto extends PartialType(CreatePersonDto) {}

在更新的Controller使用这个CreatePersonDto就可以了。

我在写本地demo的时候,发现PartialType在@nest/swagger下不存在。如果你也有这个问题,需要升级swagger这个包。~~~~

more

PickType()

功能从一个输入类型中选择一部分属性来创建一个新类型(类)

重点是选择一部分

class PersonDTO {
 @ApiProperty({
    message: '',
    type: String,
 })
 name: string;
 
 @ApiProperty({
    message: '',
    type: String,
 })
 hintText: string;
 ...
}

我们只需要hintTextname

只需要这么写

class updateDTO extends PickType(PersonDTO,['name','hintText']){}

updateDTO只有namehintText两个属性。

PickType显然很有用

OmitType

OmitTypePickType功能是相反的,写法也一样。
移除指定的输入属性。

IntersectionType

IntersectionType()函数将两种类型组合成一个新类型.

export class UpdateCatDto extends IntersectionType(CreateCatDto, AdditionalCatInfo) {}

注意是将两种输入类变成一个输入类,把两个类的所有属性合并为一个类

  • PartialType是类的所有成员全部变成可选的。
  • PickType对指定输入类选择指定的成员并返回一个类。
  • OmitType对指定输入类排除指定的成员并返回一个类。
  • IntersectionType是合并两个输入类,合并所有成员。

更强的组合写法

函数类映射是支持组合的写法的。

export class UpdateCatDto extends PartialType( OmitType(CreateCatDto, ['name'] as const), ) {}

常用的枚举类型

ts中有一个枚举类型为enum.

在日常的业务中,常有一些业务类型的判断。

如以下场景 ,porductType,1对应类型A,2对应类型B,未来会继续拓展。

我们在代码中如果直接判断vlaue,维护起来就会难以理解

if(data.porductType === 1) {
  dosomething
}else {

  其它产品
}

此时引入一个枚举就很适用

enum prodcTypeEnum {
    typeA = '1',
    typeB = '2',
    ...
}

业务代码判断类型就成为了如下的形式


if( data.type === prodcTypeEnum[typeA]){
}

枚举在业务中很常见,某个字段局限于确定的几个值,这便是枚举的使用场景.

设置ApiProperty类型为具体的数组值。如果被装饰的字段是数组,还需要设置IsArraytrue.

class User {
@ApiProperty({
    enum: ['Admin','SuperAdmin','User'],
    isArray: true,
})
role: UserRole;
}

enum UserRole {
 Admin = `Admin`,
 SuperAdmin = `SuperAdmin`,
...
}

你可能感兴趣的