nestjs中集成swagger文档
nestjs项目生成 swagger 文档
注意:
- 关于生成 swagger 的插件,只能生成文档,或者调整文档的 ui ,不会对项目本身逻辑产生影响。
- 若要开启auth验证需要一定的配置才可用。
1. 安装依赖
pnpm i @nestjs/swagger swagger-ui-express
@nestjs/swagger:NestJS 官方 Swagger 模块,提供装饰器和文档生成逻辑。swagger-ui-express:提供 Swagger UI 界面,用于可视化展示文档。
2. 创建 swagger 配置文件
export const swaggerSetup = (app: INestApplication) => {// 1. 配置 Swagger 文档const config = new DocumentBuilder().setTitle('NestJS API') // 文档标题.setDescription('这是一个基于 NestJS 的 API 文档, 主要描述了一个图书管理系统') // 文档描述.setVersion('1.0') // 文档版本.addTag('权限校验') // 添加标签(用于归类接口).addTag('身份管理').addTag('用户管理').addTag('图书管理').addBearerAuth({type: 'http',scheme: 'bearer',bearerFormat: 'JWT',name: 'Authorization',description: '请输入您的 JWT 令牌',in: 'header',},'token',) // 支持 JWT 认证(可选).build();// 2. 生成 Swagger 文档const document = SwaggerModule.createDocument(app, config);// 3. 挂载 Swagger UI 到指定路径(默认 /api-docs)SwaggerModule.setup('api-docs', app, document,{swaggerOptions: {docExpansion: 'none', // 控制是否展开所有文档persistAuthorization: true, // 保持授权信息tagsSorter: 'alpha', // 按标签排序},});
};
3. 在控制器中使用swagger的相关装饰器
@ApiTags():
用于指定接口所属的标签。可在配置中添加标签,然后通过标签来过滤接口。@ApiOperation():
用于描述接口的用途。@ApiParam():
用于描述接口的参数。@ApiQuery():
用于描述接口的查询参数。@ApiBody():
用于描述接口的请求体参数。@ApiResponse():
用于描述接口的响应参数。@ApiBearerAuth():
用于描述接口需要 JWT 认证。@ApiOkResponse():
用于描述接口的返回参数。@ApiCreatedResponse():
用于描述接口的返回参数。@ApiSecurity('token'):
设置鉴权,参数对应的鉴权名称。
