如何在NestJS中使用@nestjs/swagger和nest-knife4j为API添加请求示例?

Question

@nestjs/swagger结合nest-knife4j实现接口文档怎么添加请求示例？

网上nestjs中使用的先例比较少，把能尝试的api测了一下，没找到结果

我希望在这里添加JSON格式的请求示例，这样我就可以复制到调试中进行测试。
我不知道使用哪个api,最好能提供一个完整示例。

Answer 1

要在NestJS中使用@nestjs/swagger和nest-knife4j为API添加请求示例，你需要遵循以下步骤：

1. 安装必要的包

确保你已经安装了@nestjs/swagger和nest-knife4j。如果没有，请通过npm或yarn进行安装：

npm install --save @nestjs/swagger nest-knife4j# 或yarn add @nestjs/swagger nest-knife4j

2. 配置SwaggerModule

在你的NestJS应用中，你需要配置SwaggerModule。通常，这是在主模块（如AppModule）中完成的。

import { Module } from '@nestjs/common';import { AppController } from './app.controller';import { AppService } from './app.service';import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';import { Knife4jModule } from 'nest-knife4j';@Module({  imports: [    Knife4jModule.forRoot({      // Knife4j的配置项    }),  ],  controllers: [AppController],  providers: [AppService],})export class AppModule {  configure(consumer: MiddlewareConsumer) {    const options = new DocumentBuilder()      .setTitle('My API')      .setDescription('My API description')      .setVersion('1.0')      .addBearerAuth()      .build();    const document = SwaggerModule.createDocument(this, options);    SwaggerModule.setup('api', this, document);  }}

3. 为控制器和方法添加Swagger装饰器

在你的控制器和方法上，使用@ApiTags(), @ApiOperation(), @ApiConsumes(), @ApiProduces(), @ApiBearerAuth(), @ApiParam(), @ApiBody(), @ApiResponse()等装饰器来描述你的API。

例如，为了一个POST请求，你可能想这样做：

import { Controller, Post, Body } from '@nestjs/common';import { ApiTags, ApiOperation, ApiConsumes, ApiProduces, ApiResponse, ApiBody } from '@nestjs/swagger';@Controller('example')@ApiTags('Example')export class ExampleController {  @Post()  @ApiOperation({ summary: 'Create an example' })  @ApiConsumes('application/json')  @ApiProduces('application/json')  @ApiResponse({    status: 201,    description: 'The record has been successfully created.',    type: ExampleDto,  })  @ApiBody({ type: ExampleDto })  async create(@Body() exampleDto: ExampleDto) {    // your implementation here  }}

4. 为请求添加示例

要在Swagger UI中为你的请求添加JSON示例，你可以在@ApiBody()装饰器中指定example属性。

@ApiBody({  type: ExampleDto,  example: {    field1: 'value1',    field2: 'value2',    // ...其他字段  },})

5. 启动应用并查看Swagger UI

当你启动NestJS应用后，访问http://localhost:3000/api（或你设置的任何其他路径）来查看Swagger UI。在那里，你应该能看到你的API文档，包括你添加的请求示例。

希望这可以帮助你！如果你有任何其他问题或需要进一步的澄清，请告诉我。