Nestjs项目实战 使用Swagger自动生成API文档

在Nestjs项目中集成Swagger时遇到了几个问题：

  1. 如何通过装饰器自动生成完整的API文档？@ApiProperty和@ApiOperation等常用注解总是配置不完整
  2. 生成的SwaggerUI页面无法显示嵌套的DTO对象结构，试过@ApiExtraModels也没效果
  3. 接口分组展示有没有最佳实践？目前所有路由都混在Default组里
  4. 生产环境想关闭Swagger文档，但保留开发环境可用，该怎么配置？
  5. 文档中的枚举类型总是显示为数字，如何让Swagger展示实际的枚举值字符串？
    求有实际项目经验的大佬分享解决方案

3 回复

在NestJS项目中使用Swagger自动生成API文档非常简单。首先安装依赖：npm install @nestjs/swagger swagger-ui-express。

接着，在AppModule中配置Swagger模块：

import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

@Module({})
export class AppModule {}

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('API 文档')
    .setDescription('接口说明')
    .setVersion('1.0')
    .addTag('API')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

然后在你的Controller中添加装饰器来描述接口，例如：

import { Controller, Get, Param, Query } from '@nestjs/common';
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';

@ApiTags('示例')
@Controller('example')
export class ExampleController {
  @Get()
  @ApiOperation({ summary: '获取示例列表' })
  @ApiResponse({ status: 200, description: '成功' })
  getItems(@Query('page') page: number) {
    return [];
  }

  @Get(':id')
  @ApiOperation({ summary: '根据ID获取示例' })
  @ApiResponse({ status: 200, description: '成功' })
  getItem(@Param('id') id: string) {
    return {};
  }
}

这样访问/api就能看到生成的API文档了。


在Nestjs项目中使用Swagger生成API文档非常简单。首先安装依赖：

npm install @nestjs/swagger swagger-ui-express --save

然后在AppModule里配置Swagger：

import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

@Module({
  // ...
})
export class AppModule {
  static async bootstrapWithSwagger(app) {
    const options = new DocumentBuilder()
      .setTitle('API 文档')
      .setDescription('我的Nestjs API文档')
      .setVersion('1.0')
      .addTag('example') // 标签
      .build();
    const document = SwaggerModule.createDocument(app, options);
    SwaggerModule.setup('api', app, document);
  }
}

启动应用后访问/api即可看到自动生成的API文档。记得在Controller的方法上添加@ApiTags和@ApiOperation等装饰器来丰富文档内容。

比如：

@ApiTags('example')
@Controller('example')
export class ExampleController {
  @Get()
  @ApiOperation({ summary: '获取示例数据' })
  get(): string {
    return 'Hello Swagger!';
  }
}

这样就完成了基本的配置，可以根据需求进一步定制化Swagger文档。

在NestJS项目中使用Swagger自动生成API文档的步骤如下：

  1. 安装依赖
npm install @nestjs/swagger swagger-ui-express
  1. 在main.ts中配置Swagger
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const config = new DocumentBuilder()
    .setTitle('API文档')
    .setDescription('API接口文档')
    .setVersion('1.0')
    .addBearerAuth() // 支持Bearer token
    .build();
  
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document);

  await app.listen(3000);
}
  1. 在控制器中使用装饰器
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';

[@ApiTags](/user/ApiTags)('用户管理')
@Controller('users')
export class UsersController {
  [@ApiOperation](/user/ApiOperation)({ summary: '创建用户' })
  [@ApiResponse](/user/ApiResponse)({ status: 201, description: '用户创建成功' })
  @Post()
  create() {
    return '用户创建成功';
  }
  
  [@ApiOperation](/user/ApiOperation)({ summary: '获取用户列表' })
  @Get()
  findAll() {
    return [];
  }
}
  1. 为DTO添加Swagger装饰器
import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
  [@ApiProperty](/user/ApiProperty)({ description: '用户名' })
  username: string;
  
  [@ApiProperty](/user/ApiProperty)({ description: '密码' })
  password: string;
}
  1. 访问文档 启动项目后，访问 http://localhost:3000/api-docs 即可查看API文档

常用装饰器：

通过合理使用这些装饰器，可以生成完整的API文档，方便前端开发人员使用。

回到顶部