返回

nestjs-swagger：如何配置参数校验与请求响应

后端

如何使用 NestJS 和 Swagger 为您的 API 注入生命力

引言

在当今快节奏的数字世界中，创建健壮且易于使用的 API 对于任何应用程序的成功至关重要。NestJS 和 Swagger 是两大出色的工具，可帮助您为 API 带入令人惊叹的功能，例如参数校验、请求响应配置以及输入输出结构。在这篇深入的文章中，我们将深入探讨如何使用这些工具来提升您的 API 开发体验。

1. 安装 NestJS 和 Swagger

踏上旅程的第一步是安装 NestJS 和 Swagger。对于 NestJS，您可以使用以下命令：

npm install -g @nestjs/cli
nest new my-app

对于 Swagger，使用此命令：

npm install --save @nestjs/swagger

2. 配置 Swagger

接下来，您需要配置 Swagger。在 src 目录中，创建一个名为 swagger.json 的文件。该文件将包含 Swagger 文档的元数据。以下是示例内容：

{
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "description": "This is my API documentation.",
    "version": "1.0.0"
  },
  "paths": {}
}

3. 定义控制器和路由

控制器和路由是 API 的核心。在 src/app.controller.ts 文件中，添加以下代码：

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { AppService } from './app.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }

  @Post('users')
  createUser(@Body() createUserDto: CreateUserDto) {
    return this.appService.createUser(createUserDto);
  }
}

在这个控制器中，我们定义了两个路由：GET /（返回 "Hello World!"）和 POST /users（用于创建新用户）。

4. 定义数据传输对象 (DTO)

DTO 用于在请求和响应之间传输数据。在 src/dto/create-user.dto.ts 文件中，添加以下代码：

export class CreateUserDto {
  name: string;
  email: string;
  password: string;
}

这个 DTO 定义了创建新用户所需的数据。

5. 添加参数校验

NestJS 提供了参数校验功能。在 AppController 中，添加以下代码：

import { Body, Param, ValidationPipe } from '@nestjs/common';

...

@Post('users')
createUser(@Body(new ValidationPipe()) createUserDto: CreateUserDto) {
  return this.appService.createUser(createUserDto);
}

我们使用 @ValidationPipe() 装饰器对 createUserDto 进行参数校验，确保它符合指定的模式。

6. 添加请求响应配置

Swagger 允许您配置请求响应。在 AppController 中，添加以下代码：

import { ApiOperation, ApiResponse } from '@nestjs/swagger';

...

@Post('users')
@ApiOperation({ summary: 'Create a new user' })
@ApiResponse({ status: 201, description: 'The user has been successfully created.' })
createUser(@Body(new ValidationPipe()) createUserDto: CreateUserDto) {
  return this.appService.createUser(createUserDto);
}

我们使用 @ApiOperation() 和 @ApiResponse() 装饰器来指定路由的摘要和响应。这将显示在 Swagger 文档中。

7. 运行应用程序

最后，使用以下命令运行您的应用程序：

npm run start

然后，访问 http://localhost:3000/swagger/index.html 查看 Swagger 文档。

常见问题解答

  1. 什么是 Swagger？
    Swagger 是一款流行的工具，用于生成 API 文档并促进 API 的发现和使用。

  2. NestJS 和 Swagger 如何协同工作？
    NestJS 提供了功能强大的功能，而 Swagger 则提供了 API 文档和配置选项，共同为开发人员提供了构建健壮且易于使用的 API 的强大组合。

  3. 如何配置参数校验？
    您可以使用 NestJS 的 @ValidationPipe() 装饰器来配置参数校验，它将根据指定的模式对请求体进行验证。

  4. 如何配置请求响应？
    Swagger 提供了 @ApiOperation() 和 @ApiResponse() 装饰器来配置请求摘要和响应。

  5. 如何查看 Swagger 文档？
    运行应用程序后，访问 http://localhost:3000/swagger/index.html 查看 Swagger 文档。

结论

使用 NestJS 和 Swagger，您可以将 API 开发提升到一个新的水平。通过利用这些工具，您可以实现严格的参数校验、定制的请求响应配置以及全面的 API 文档，从而为您的用户提供无缝的体验。通过掌握这些技巧，您将为构建可靠、用户友好的 API 奠定坚实的基础。