乐闻世界logo
搜索文章和话题
如何在NestJS中集成Swagger

如何在NestJS中集成Swagger

乐闻的头像
乐闻

2024年01月12日 11:26· 阅读 402

前言

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

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

集成步骤

一、安装 Swagger 模块

在你的NestJS项目中,安装 @nestjs/swaggerswagger-ui-express

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

二、设置 Swagger 模块

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

typescript
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:

typescript
import { ApiProperty } from '@nestjs/swagger'; export class CreateCatDto { @ApiProperty() name: string; @ApiProperty() age: number; @ApiProperty() breed: string; }

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

typescript
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应用:

shell
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中添加安全配置:

typescript
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版本。

    typescript
    // 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都应该有一个对应的文档对象。每个文档对象都可以有自定义的配置。

    typescript
    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应用:

    shell
    npm run start

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

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

总结

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

标签: