by 雪隐 from https://juejin.cn/user/1433418895994094
本文欢迎分享与聚合，全文转载就不必了，尊重版权，圈子就这么大，若急用可联系授权
大家好，很开心又和大家见面了，这一章的内容比较简单，导入SwaggerUI。导入Swagger的目的主要是为了给前端的伙伴提供一个可视化的窗口。让前端知道后端能够提供给他们什么接口。这一点在团队合作中是非常有必要的。
在官网的文档中有详细介绍到SwaggerUI的用法。
SwaggerUI
Swagger是一种工具集，用于设计、构建、文档化和测试Web服务API。它支持多种编程语言和框架，可以生成易于阅读和理解的API文档，提供交互式API探索和调试功能。 Swagger包括一个开源的规范和一组开源工具，可以帮助开发人员在设计、构建和测试API时更轻松地协作。它还提供了一些高级功能，如API版本控制、授权和身份验证。Swagger已经成为了一个非常流行的API工具集，被广泛用于构建和文档化现代Web服务API。
使用Swagger有以下几个主要优点：
- 文档自动生成：Swagger可以根据代码自动生成易于阅读的API文档，减少手动编写文档的工作量。
- 提高可维护性：API的变更是不可避免的，使用Swagger可以帮助开发人员快速了解API的结构和用法，从而更容易地进行维护。
- 提高互操作性：Swagger的规范和工具支持多种编程语言和框架，使得不同的开发团队能够更容易地协作开发API，提高API的互操作性。
- 改进测试流程：Swagger提供了交互式API测试和探索功能，可以帮助开发人员更快速、更准确地进行API测试和调试。
- 提高API的可重用性：使用Swagger可以使API更加模块化和可重用，从而降低了开发成本和复杂度。
综上所述，Swagger是一种方便的工具，可以提高API的可维护性、可测试性和可重用性，同时提高了团队之间的协作效率。
在NestJS中使用 Swagger
在NestJS中使用Swagger可以让我们更方便地生成API文档，并且提供交互式API探索和测试功能。以下是使用Swagger的步骤：
- 安装Swagger模块：在NestJS中，我们可以使用
@nestjs/swagger模块来集成Swagger。可以使用以下命令来安装该模块：
npm install --save @nestjs/swagger
- 在
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的页面。
- 在控制器中添加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探索和测试功能。
其他优化
有些内容比较少，就一起在这一章介绍一下
- 全局前缀
在
main.ts里面加上全局前缀。
// 加上全局前缀
app.setGlobalPrefix('api');
2.版本化管理
参照我之前写的小技巧，大家根据自己的需求，在main.ts中加入版本化管理
// 接口版本化管理
app.enableVersioning({ type: VersioningType.URI });
- 热重载
// 热重载
if (module.hot) {
module.hot.accept();
module.hot.dispose(() => app.close());
}
