nest中常用的swagger写法

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

还可以去写swagger文档。

在nest的controller写法中，代码如下

//person.controller.ts

@Post()
async create(@Body() person: PersonDTO): Promise<Person> {
  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支持的Type有String,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这个包。~~~~

`PickType()`

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

重点是选择一部分

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

我们只需要hintText与name

只需要这么写

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

updateDTO只有name与hintText两个属性。

PickType显然很有用

`OmitType`

OmitType与PickType功能是相反的，写法也一样。
移除指定的输入属性。

`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类型为具体的数组值。如果被装饰的字段是数组，还需要设置IsArray为true.

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

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