使用Nest.js集成Swagger：全面提升API文档管理

引言

Swagger是一个强大的工具，可以帮助开发者自动生成API文档。在Nest.js项目中集成Swagger，可以大大提升API管理和测试的效率。本篇博客将详细介绍如何在Nest.js项目中集成Swagger，并展示一些高级用法。

安装Swagger

首先，我们需要安装@nestjs/swagger包：

npm install --save @nestjs/swagger

参考文档：Nest.js Swagger文档

在main文件中使用Swagger

接下来，在main.ts文件中设置Swagger配置：

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const config = new DocumentBuilder()
    .setTitle('接口文档')
    .setDescription('描述')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document);
  await app.listen(3000, () => {
    console.log('127.0.0.1:3000');
  });
}

bootstrap();

启动服务

启动Nest.js服务后，访问 http://localhost:3000/docs，你将看到根据代码自动生成的接口文档。

设置标签

使用@ApiTags装饰器为控制器设置标签，以便更好地组织和展示API文档：

import { Controller } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';

@ApiTags('用户')
@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
}

给每一个请求方法命名

使用@ApiOperation装饰器为每个请求方法添加描述，提高文档的可读性：

import { Post, Body } from '@nestjs/common';
import { ApiOperation } from '@nestjs/swagger';

export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  @ApiOperation({ summary: '添加用户' })
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }
}

添加默认参数

通过创建DTO类并使用@ApiProperty装饰器，可以为请求参数添加描述和默认值，确保API文档更加详细和准确：

import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
  @ApiProperty({
    description: '邮箱',
  })
  readonly email: string;

  @ApiProperty({
    description: '密码',
    default: '123456',
  })
  password: string;
}

总结

通过本节内容，你学习了如何在Nest.js项目中集成Swagger，从安装配置到高级用法，提高了API文档的管理和可读性。Swagger的集成使得API文档的生成和维护变得更加轻松、高效。