nestjs系列 - Swagger API
type
status
date
slug
summary
tags
category
icon
password
安装Swagger
pnpm i @nestjs/swagger在Nestjs项目启用
DocumentBuilder 属性
方法 | 描述 |
setTitle | 文档标题 |
setDescription | 文档描述 |
setVersion | 文档版本 |
setTermsOfService | 文档服务条款 |
setContact | 文档联系信息 |
setLicense | 文档许可证信息 |
addServer | 文档服务地址 |
setExternalDoc | 文档外部链接 |
setBasePath | 设置文档基础路径 |
addTag | 添加文档标签 |
addExtension | 添加扩展 |
addSecurity | 添加安全方案 |
addGlobalParameters | 添加全局参数 |
addSecurityRequirements | 添加安全需求 |
addBearerAuth | 添加 Bearer Token 认证 |
addOAuth2 | 添加 OAuth2 认证 |
addApiKey | 添加 ApiKey |
addBasicAuth | 添加基础认证 |
addCookieAuth | 添加 Cookie 认证 |
build | 构建服务 |
ㅤ | ㅤ |
在Dto class添加装饰器
常用 Swagger 装饰器
装饰器 | 描述 |
@ApiTags | 为控制器或方法添加标签，用于组织 Swagger UI 文档 |
@ApiOperation | 为控制器方法添加操作描述，包括摘要和详细描述 |
@ApiParam | 描述路径参数、请求参数或响应参数，包括名称、类型、描述等 |
@ApiBody | 指定请求体的 DTO 类型，用于描述请求体的结构 |
@ApiResponse | 描述 API 的响应，包括状态码、描述等 |
@ApiBearerAuth | 指定请求需要携带 Bearer Token，用于身份验证 |
@ApiProperty | 为 DTO 类型的属性添加元数据，如描述、默认值等 |
@ApiQuery | 描述查询参数，包括名称、类型、描述等 |
@ApiHeader | 描述请求头信息，包括名称、类型、描述等 |
@ApiExcludeEndpoint | 标记一个控制器方法不在 Swagger UI 中显示 |
问题
相比C# MVC项目的Swagger使用，感觉Nestjs引入Swagger还是太复杂了。
首选，每个dto实体都需要给全部属性添加上@ApiProperty，否则无法正常识别对应的dto属性；
其次，如果dto的属性配置太不智能，例如，entity往往有typeorm的comment，为何不能直接把它作为api属性的描述？
所以，我再探索prisma，并使用prisma schema统一化驱动typeorm entity、class-valitaion dto、swagger-api、restful api的搭建