![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/a23c7e80c7664656b1437f81803cad41.webp#pic_center)
安装依赖
pnpm install @nestjs/swagger class-validator
在 main.ts 中定义 SwaggerModule 类
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('water-admin')
.setDescription('Background system based on Nest.js + Vue3 full stack')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);
await app.listen(3000);
}
bootstrap();
方法 | 描述 |
---|
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 中使用装饰器
import { ApiProperty } from '@nestjs/swagger';
import { IsNumberString, IsOptional, IsUUID } from 'class-validator';
export class CreateWaterDto {
@ApiProperty({
type: String,
description: '岗位名称',
required: false,
default: '前端工程师',
})
name?: string;
@ApiProperty({
type: String,
description: '所属组织',
default: 'f45cd48b-e703-49db-91be-ae7f594e73e0',
required: false,
})
@IsOptional()
@IsUUID('all', { message: 'orgId 参数不正确' })
orgId?: string;
@ApiProperty({
type: Number,
description: '开始日期',
default: 1721145600000,
required: false,
})
@IsOptional()
@IsNumberString({}, { message: '开始日期必须是时间戳格式' })
startTime?: number;
@ApiProperty({
type: Number,
description: '结束日期',
default: 1721318399999,
required: false,
})
@IsOptional()
@IsNumberString({}, { message: '结束日期必须是时间戳格式' })
endTime?: number;
}
在 Controller 控制器 中使用装饰器
import {
Controller,
Get,
Post,
Body,
Patch,
Param,
Delete,
} from '@nestjs/common';
import { WaterService } from './water.service';
import { CreateWaterDto } from './dto/create-water.dto';
import { UpdateWaterDto } from './dto/update-water.dto';
import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
@ApiTags('岗位管理')
@Controller('water')
export class WaterController {
constructor(private readonly waterService: WaterService) {}
@Post()
@ApiOkResponse({ type: CreateWaterDto })
@ApiOperation({ summary: '获取岗位管理列表' })
create(@Body() createWaterDto: CreateWaterDto) {
return 'ff------ 火箭 🚀';
}
@Get()
findAll() {
return this.waterService.findAll();
}
@Get(':id')
findOne(@Param('id') id: string) {
return this.waterService.findOne(+id);
}
@Patch(':id')
update(@Param('id') id: string, @Body() updateWaterDto: UpdateWaterDto) {
return this.waterService.update(+id, updateWaterDto);
}
@Delete(':id')
remove(@Param('id') id: string) {
return this.waterService.remove(+id);
}
}
![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/e5d2fba9248a41b99539e892949ef732.png)
常用 Swagger 装饰器
装饰器 | 描述 |
---|
@ApiTags | 为控制器或方法添加标签,用于组织 Swagger UI 文档 |
@ApiOperation | 为控制器方法添加操作描述,包括摘要和详细描述 |
@ApiParam | 描述路径参数、请求参数或响应参数,包括名称、类型、描述等 |
@ApiBody | 指定请求体的 DTO 类型,用于描述请求体的结构 |
@ApiResponse | 描述 API 的响应,包括状态码、描述等 |
@ApiBearerAuth | 指定请求需要携带 Bearer Token,用于身份验证 |
@ApiProperty | 为 DTO 类型的属性添加元数据,如描述、默认值等 |
@ApiQuery | 描述查询参数,包括名称、类型、描述等 |
@ApiHeader | 描述请求头信息,包括名称、类型、描述等 |
@ApiExcludeEndpoint | 标记一个控制器方法不在 Swagger UI 中显示 |