NestJS博客实战10-SwaggerUI

1,097 阅读4分钟
by 雪隐 from https://juejin.cn/user/1433418895994094
本文欢迎分享与聚合,全文转载就不必了,尊重版权,圈子就这么大,若急用可联系授权

大家好,很开心又和大家见面了,这一章的内容比较简单,导入SwaggerUI。导入Swagger的目的主要是为了给前端的伙伴提供一个可视化的窗口。让前端知道后端能够提供给他们什么接口。这一点在团队合作中是非常有必要的。

在官网的文档中有详细介绍到SwaggerUI的用法。

SwaggerUI

Swagger是一种工具集,用于设计、构建、文档化和测试Web服务API。它支持多种编程语言和框架,可以生成易于阅读和理解的API文档,提供交互式API探索和调试功能。 Swagger包括一个开源的规范和一组开源工具,可以帮助开发人员在设计、构建和测试API时更轻松地协作。它还提供了一些高级功能,如API版本控制、授权和身份验证。Swagger已经成为了一个非常流行的API工具集,被广泛用于构建和文档化现代Web服务API。

使用Swagger有以下几个主要优点:

  1. 文档自动生成:Swagger可以根据代码自动生成易于阅读的API文档,减少手动编写文档的工作量。
  2. 提高可维护性:API的变更是不可避免的,使用Swagger可以帮助开发人员快速了解API的结构和用法,从而更容易地进行维护。
  3. 提高互操作性:Swagger的规范和工具支持多种编程语言和框架,使得不同的开发团队能够更容易地协作开发API,提高API的互操作性。
  4. 改进测试流程:Swagger提供了交互式API测试和探索功能,可以帮助开发人员更快速、更准确地进行API测试和调试。
  5. 提高API的可重用性:使用Swagger可以使API更加模块化和可重用,从而降低了开发成本和复杂度。

综上所述,Swagger是一种方便的工具,可以提高API的可维护性、可测试性和可重用性,同时提高了团队之间的协作效率。

在NestJS中使用 Swagger

在NestJS中使用Swagger可以让我们更方便地生成API文档,并且提供交互式API探索和测试功能。以下是使用Swagger的步骤:

  1. 安装Swagger模块:在NestJS中,我们可以使用@nestjs/swagger模块来集成Swagger。可以使用以下命令来安装该模块:
npm install --save @nestjs/swagger
  1. main.ts文件中添加Swagger的配置:可以通过SwaggerModule提供的setup()方法来配置Swagger。示例代码如下:
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('雪隐博客')
    .setDescription('博客项目')
    .setVersion('0.0.1')
    .build();

  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('/api/doc', app, document, {
    // 个性化样式
    customCssUrl: '/css/theme-outline.css',
  });
  
  await app.listen(3000);
}
bootstrap();

这里通过DocumentBuilder创建Swagger的基本信息,然后通过SwaggerModule.createDocument()方法生成文档对象,并通过SwaggerModule.setup()方法将文档绑定到应用的/api/doc路由上。

除此之外,还可以自定义Swagger样式,参照我之前写的小技巧个性化Swagger的页面。

  1. 在控制器中添加Swagger的注解:在控制器的方法上添加Swagger的注解,例如@ApiTags()@ApiOperation()@ApiResponse()等,可以让Swagger自动生成API文档。为了优化和减少工作量,大家可以参照我写的小技巧1,通过自定义装饰器的方法,来简化这个步骤。

简化之后,接口的示例代码如下:

import { Controller, Post, Body } from '@nestjs/common';
import { UserService } from './user.service';
import { CreateUserDto } from './dto/create-user.dto';
import { SwaggerDocumentation } from 'src/common/decorator/swagger.decorator';

@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post('create')
  @SwaggerDocumentation('创建用户', '返回创建结果', 'bad request例子', String)
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto);
  }
}

总之,使用Swagger可以让我们更加方便地生成API文档,并提供交互式API探索和测试功能。

其他优化

有些内容比较少,就一起在这一章介绍一下

  1. 全局前缀 在main.ts里面加上全局前缀。
  // 加上全局前缀
  app.setGlobalPrefix('api');

2.版本化管理 参照我之前写的小技巧,大家根据自己的需求,在main.ts中加入版本化管理

  // 接口版本化管理
  app.enableVersioning({ type: VersioningType.URI });
  1. 热重载
  // 热重载
  if (module.hot) {
    module.hot.accept();
    module.hot.dispose(() => app.close());
  }

本章代码

代码