一篇文章学会如何轻松集成 Swagger 到 NestJS 项目

前言

NestJS是一个高效且适用于构建服务器端应用程序的框架，它基于Node.js并且被设计为灵活和可伸缩。Swagger，现在更多被称为OpenAPI，是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。集成Swagger到NestJS可以大大提高你的API的文档质量，并提供一个交互式的用户界面，供开发人员和最终用户使用。

本文将详细介绍如何在 NestJS 项目中集成 Swagger。

集成步骤

一、安装 Swagger 模块

在你的NestJS项目中，安装 @nestjs/swagger和 swagger-ui-express：

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

二、设置 Swagger 模块

在你的NestJS应用程序中设置Swagger模块非常简单。首先，打开 main.ts文件，并添加以下代码：

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

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

  // 创建Swagger选项
  const options = new DocumentBuilder()
    .setTitle('Example API')
    .setDescription('The example API description')
    .setVersion('1.0')
    .addTag('example')
    .build();

  // 创建Swagger文档
  const document = SwaggerModule.createDocument(app, options);

  // 设置`/api`路由为Swagger文档及其UI的主页
  SwaggerModule.setup('api', app, document);

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

这段代码做了几件事情：

1. 导入Swagger相关的模块。
2. 使用 DocumentBuilder来构建Swagger文档的基本信息。
3. 使用 SwaggerModule生成并注册了Swagger文档和UI。

三、添加API模型和控制器注解

为了能够在Swagger文档中清晰地展示你的API，你需要在控制器和模型(Data Transfer Objects, DTOs)中添加一些装饰器。首先来定义一个DTO：

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

export class CreateCatDto {
  @ApiProperty()
  name: string;

  @ApiProperty()
  age: number;

  @ApiProperty()
  breed: string;
}

然后在你的控制器中使用Swagger装饰器来描述操作：

import { Body, Controller, Get, Post } from '@nestjs/common';
import { CreateCatDto } from './create-cat.dto';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';

@ApiTags('cats')
@Controller('cats')
export class CatsController {
  @Post()
  @ApiOperation({ summary: 'Create cat' })
  @ApiResponse({ status: 403, description: 'Forbidden.' })
  async create(@Body() createCatDto: CreateCatDto) {
    return 'This action adds a new cat';
  }

  @Get()
  @ApiOperation({ summary: 'Get all cats' })
  async findAll() {
    return 'This action returns all cats';
  }
}

四、运行你的应用并访问Swagger UI

最后，运行你的NestJS应用：

npm run start

打开你的浏览器并访问http://localhost:3000/api。你会看到一个漂亮的Swagger UI界面，你可以在这里查看你所有的API端点、模型以及可以直接尝试API调用。

五、利用Swagger UI进行API测试

Swagger UI不仅仅是一个API文档说明界面，它还允许你直接在网页上测试你的API。要测试一个API，只需点击对应的API端点，然后点击“Try it out”按钮，你就可以填写需要的参数，提交请求，并立即看到响应。

比如，如果你想要测试刚才创建的“Create cat”API：

1. 在Swagger UI界面找到 POST /cats端点。
2. 点击它以展开API的详细信息。
3. 点击“Try it out”。
4. 填写请求体数据，比如输入一个新的猫咪信息。
5. 点击“Execute”。

Swagger UI会发送一个HTTP POST请求到你的NestJS服务器，并显示服务器返回的响应数据。

进阶使用

Swagger 和 NestJS 的组合非常强大，可以根据你的需要进行深度定制。

一、定制 Swagger UI

NestJS和Swagger提供了许多定制选项，比如添加授权机制、选择主题等。比如，如果你的API需要一个API密钥或者Bearer令牌，你可以在 DocumentBuilder中添加安全配置：

const options = new DocumentBuilder()
  .setTitle('Example API')
  .setDescription('The example API description')
  .setVersion('1.0')
  .addBearerAuth()  // 添加Bearer认证
  .build();

这样，在Swagger UI中测试API时，你就可以输入你的认证信息了。

二、使用分组功能来组织不同版本的API文档

在大型的API项目中，经常会有不同版本的API共存。NestJS和Swagger提供了API分组的功能，这允许你为不同版本的API创建独立的Swagger文档。以下是如何使用分组功能来组织不同版本的API文档的步骤：

1. 创建不同版本的API模块

   首先，你需要定义不同版本的API。在NestJS中，你通常会通过创建不同的模块来组织这些版本。例如，你可能会有一个 V1Module和一个 V2Module来区分你的API版本。

   // v1.module.ts
   import { Module } from '@nestjs/common';
   import { V1Controller } from './v1.controller';
   
   @Module({
     controllers: [V1Controller],
   })
   export class V1Module {}
   
   // v2.module.ts
   import { Module } from '@nestjs/common';
   import { V2Controller } from './v2.controller';
   
   @Module({
     controllers: [V2Controller],
   })
   export class V2Module {}
   
   

2. 为每个版本创建Swagger文档

   在 main.ts中，你需要创建不止一个Swagger文档对象，每个版本的API都应该有一个对应的文档对象。每个文档对象都可以有自定义的配置。

   async function bootstrap() {
     const app = await NestFactory.create(AppModule);
   
     // 创建第一个版本的Swagger选项
     const optionsV1 = new DocumentBuilder()
       .setTitle('API Version 1')
       .setDescription('API Version 1 description')
       .setVersion('1.0')
       .addTag('v1')
       .build();
   
     const documentV1 = SwaggerModule.createDocument(app, optionsV1, {
       include: [V1Module], // 只包含V1Module模块
     });
     SwaggerModule.setup('api/v1', app, documentV1);
   
     // 创建第二个版本的Swagger选项
     const optionsV2 = new DocumentBuilder()
       .setTitle('API Version 2')
       .setDescription('API Version 2 description')
       .setVersion('2.0')
       .addTag('v2')
       .build();
   
     const documentV2 = SwaggerModule.createDocument(app, optionsV2, {
       include: [V2Module], // 只包含V2Module模块
     });
     SwaggerModule.setup('api/v2', app, documentV2);
   
     // 其他配置...
   
     await app.listen(3000);
   }
   bootstrap();
   
   

   在上述代码中，我使用 include选项为每个版本的文档包含了不同的模块，这样Swagger UI就可以针对不同的版本显示不同的API。

3. 启动应用并检查分组文档

   启动你的NestJS应用：

   npm run start
   
   

   现在，你可以在浏览器中访问两个不同版本的Swagger UI：

   • 第一个版本的API文档：http://localhost:3000/api/v1
   • 第二个版本的API文档：http://localhost:3000/api/v2

   每个链接都将展示对应版本的API端点和模型。

总结

通过以上步骤，你已经成功在NestJS项目中集成了Swagger，并且可以利用Swagger UI来增强你的API的可视化和交互性。不仅如此，良好的API文档是提高开发效率和促进团队协作的关键。有了Swagger，你的API文档将会始终保持最新，且具有高度的可交互性。