关于nestjs: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 这个包。~~~~

more

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), ) {}

TODO: 枚举