nestjs中集成swagger文档

nestjs项目生成 swagger 文档

注意：

1. 关于生成 swagger 的插件，只能生成文档，或者调整文档的 ui ，不会对项目本身逻辑产生影响。
2. 若要开启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的相关装饰器

1. @ApiTags()：
   用于指定接口所属的标签。可在配置中添加标签，然后通过标签来过滤接口。
2. @ApiOperation()：
   用于描述接口的用途。
3. @ApiParam()：
   用于描述接口的参数。
4. @ApiQuery()：
   用于描述接口的查询参数。
5. @ApiBody()：
   用于描述接口的请求体参数。
6. @ApiResponse()：
   用于描述接口的响应参数。
7. @ApiBearerAuth()：
   用于描述接口需要 JWT 认证。
8. @ApiOkResponse()：
   用于描述接口的返回参数。
9. @ApiCreatedResponse()：
   用于描述接口的返回参数。
10. @ApiSecurity('token'):
    设置鉴权，参数对应的鉴权名称。