NestJS-Knife4j

文章目录

前言
- ✅ 一、什么是 Knife4j？
- ✅ 二、Knife4j 与 Swagger 对比
- ✅ 三、NestJS-Knife4j 集成
- - 1. 安装依赖
  - 2. 配置 Swagger 与 Knife4j
  - 3. 启动应用并访问接口文档
- ✅ 四、功能增强
- - 1. **接口分组**
  - 2. **请求/响应示例**
  - 3. **接口文档的美化**
- ✅ 五、总结

前言

NestJS-Knife4j 是一个集成 Knife4j（一个增强版的 Swagger）功能的 NestJS 插件。Knife4j 是 Swagger 的增强版，提供了更丰富的功能，优化了 UI 和接口文档的展示效果，增强了开发人员和 API 使用者的交互体验。对于已经在使用 Swagger 的项目，Knife4j 提供了一些额外的优点和增强功能。

✅ 一、什么是 Knife4j？

Knife4j 是一个基于 Swagger 的前端 UI 工具，旨在通过增强 Swagger 的功能来优化接口文档的用户体验。它在 Swagger 的基础上提供了以下增强特性：

UI 优化：提供了更加友好和直观的接口文档界面。
增强的文档交互：允许用户直接在 UI 中尝试接口请求，支持 API 测试。
丰富的功能：如支持接口分组、API 文档定制、参数样式、请求示例、数据格式展示等。
更好的性能：相比于原生 Swagger，Knife4j 提供了更快速的界面加载和渲染。

✅ 二、Knife4j 与 Swagger 对比

特性	Swagger	Knife4j
界面	基本的 API 文档展示，UI 较为简洁	改进的 UI 界面，提供更多功能，设计更美观
接口分组	支持，但自定义不多	支持多种分组方式，可以自定义接口分组，增强功能
请求示例	支持，但功能有限	支持接口请求示例、返回值示例等更详细的说明
API 测试	支持接口测试	增强的 API 测试功能，更多交互式支持
性能	较基础，加载速度较慢	更快的加载速度，支持更大的接口文档
集成方式	通过 `@nestjs/swagger` 进行集成	通过 `nestjs-knife4j` 进行集成

✅ 三、NestJS-Knife4j 集成

集成 nestjs-knife4j 可以让你快速实现 Knife4j 的增强功能，提升 API 文档体验。

1. 安装依赖

首先，安装 nestjs-knife4j 和 @nestjs/swagger（如果还没有安装的话）：

pnpm add nestjs-knife4j @nestjs/swagger swagger-ui-express

2. 配置 Swagger 与 Knife4j

在 main.ts 中配置 Swagger 和 Knife4j：

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { Knife4jModule } from 'nestjs-knife4j';async function bootstrap() {const app = await NestFactory.create(AppModule);// 设置 Swagger 配置const config = new DocumentBuilder().setTitle('My API').setDescription('API documentation with Knife4j').setVersion('1.0').addBearerAuth()  // 如果需要认证的话.build();const document = SwaggerModule.createDocument(app, config);SwaggerModule.setup('api-docs', app, document);// 配置 Knife4japp.use('/doc', Knife4jModule.setup(document, app));await app.listen(3000);
}bootstrap();

3. 启动应用并访问接口文档

启动项目后，可以访问以下两个路径：
- Swagger：http://localhost:3000/api-docs
- Knife4j：http://localhost:3000/doc

你会发现，Knife4j 提供了更为丰富的界面和更快的加载速度。

注意：如果你的swagger 集成前缀http://localhost:3000/api/v1/api-docs 的话，
由于 nestjs-knife4j 1.x 目前不支持全局前缀，/doc.html 只能在根路径访问，还是这个：http://localhost:3000/doc.html

✅ 四、功能增强

通过集成 Knife4j，你能享受到以下增强功能：

1. 接口分组

在 Swagger 中，API 的分组通常通过 tags 来实现，但 Knife4j 提供了更加直观的分组方式，并可以在 UI 中进行操作。

@ApiTags('User Management')
@Controller('users')
export class UsersController {@Get()findAll() {return this.userService.findAll();}
}

Knife4j 会自动生成清晰的接口分组，使文档更有组织性。

2. 请求/响应示例

Knife4j 支持展示接口的请求参数和返回数据示例，帮助开发人员和使用者更好地理解接口的使用方式。

@ApiOperation({ summary: 'Create a user' })
@ApiResponse({ status: 201, description: 'User created', type: User })
@Post()
create(@Body() createUserDto: CreateUserDto) {return this.userService.create(createUserDto);
}

Knife4j 会将 @ApiResponse 中的示例返回值自动展示出来。

3. 接口文档的美化

Knife4j 提供了自定义的主题，可以对 API 文档的外观进行更多定制，适应不同的 UI 风格。
提供了 RESTful 风格的接口展示，让开发者和接口使用者能够更清晰地看到接口的设计。

✅ 五、总结

功能	Swagger	Knife4j
界面美观度	较为简洁，基础功能	美化过的界面，支持更多交互
接口分组	基本支持	强大的接口分组，支持更精细化的组织方式
API 请求示例	基本支持	提供完整的请求/响应示例，增强 API 文档体验
性能	普通	更好的性能，加载速度更快
集成方式	基础的集成方式	通过 `nestjs-knife4j` 快速集成，UI 功能丰富