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`,
...
}
评论
登录后参与技术讨论,分享你的经验与见解。
登录 / 注册暂无评论