前端眼中的快乐星球：使用SwaggerUI畅游后端接口世界

NestJS 中的 SwaggerUI：提升前端开发效率和体验

何为 SwaggerUI？

对于前端开发者而言，了解后端提供的 API 接口至关重要，以便进行数据交互和页面开发。SwaggerUI 是一款强大的工具，能够生成交互式文档，详细说明所有路由、参数和响应，帮助前端开发人员一目了然地掌握 API 信息。

为何使用 SwaggerUI？

• 清晰的接口文档： SwaggerUI 可自动生成清晰简洁的接口文档，囊括所有路由详情，包括请求方法、URL、请求参数、响应结构等，使前端开发人员轻松理解并使用 API。
• 可视化界面： SwaggerUI 提供可视化界面，前端开发人员可交互式探索和测试 API。他们可在界面上直接输入请求参数，查看响应结果，尝试不同请求方法和参数组合，快速验证 API 功能和正确性。
• 代码生成： SwaggerUI 还支持代码生成功能，前端开发人员可通过 SwaggerUI 自动生成客户端代码，如 JavaScript、Java、Python 等，减少重复编写代码的工作量，提高开发效率。

如何在 NestJS 中使用 SwaggerUI？

1. 安装依赖

npm install --save @nestjs/swagger

2. 配置 SwaggerModule

在主模块文件中，导入 SwaggerModule 并配置 Swagger 文档：

// 导入 SwaggerModule
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

// 创建 Swagger 文档构建器
const config = new DocumentBuilder()
  .setTitle('API 文档')
  .setDescription('后端 API 文档')
  .setVersion('1.0')
  .addTag('API')
  .build();

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

// 配置 Swagger UI 路由
SwaggerModule.setup('/api', app, document);

3. 添加路由装饰器

在控制器中，使用 @ApiXXX 装饰器为路由添加注释，这些注释将被 SwaggerUI 用来生成接口文档。

例如：

// 导入 API 装饰器
import { ApiOperation, ApiResponse } from '@nestjs/swagger';

// 添加路由装饰器
@ApiOperation({ summary: '获取用户信息' })
@ApiResponse({ status: 200, description: '成功' })
@Get()
getUser(): User {
  return { id: 1, name: 'John Doe' };
}

4. 启动服务

运行 NestJS 应用，访问 http://localhost:3000/api，即可看到 SwaggerUI 界面。

示例代码

完整的示例代码可参考 NestJS 官方文档：https://docs.nestjs.com/openapi/introduction

结语

使用 SwaggerUI 极大地提升了前端开发人员的开发效率和体验，让他们能够轻松理解和使用后端提供的 API 接口，从而促进前后端协作和项目的顺利进行。

常见问题解答

1. 如何在 NestJS 中添加 SwaggerUI？

在 NestJS 中添加 SwaggerUI 的步骤如下：

• 安装依赖：npm install --save @nestjs/swagger
• 配置 SwaggerModule：在主模块文件中导入 SwaggerModule 并配置 Swagger 文档
• 添加路由装饰器：在控制器中使用 @ApiXXX 装饰器为路由添加注释
• 启动服务：运行 NestJS 应用并访问 SwaggerUI 界面

2. SwaggerUI 有哪些优点？

SwaggerUI 的优点包括：

• 生成清晰的接口文档
• 提供可视化界面进行交互式 API 探索和测试
• 支持代码生成，减少重复编写代码的工作量

3. 如何在路由上使用 SwaggerUI 装饰器？

在路由上使用 SwaggerUI 装饰器的示例如下：

@ApiOperation({ summary: '获取用户信息' })
@ApiResponse({ status: 200, description: '成功' })
@Get()
getUser(): User {
  return { id: 1, name: 'John Doe' };
}

4. 如何为 SwaggerUI 配置版本和标签？

在创建 Swagger 文档构建器时，可以使用 setVersion() 和 addTag() 方法指定版本和标签：

const config = new DocumentBuilder()
  .setTitle('API 文档')
  .setDescription('后端 API 文档')
  .setVersion('1.0')
  .addTag('API')
  .build();

5. 如何使用 SwaggerUI 跨域？

要使用 SwaggerUI 跨域，需要在 SwaggerModule.setup() 方法中设置 opts 参数：

SwaggerModule.setup('/api', app, document, {
  swaggerOptions: {
    docExpansion: 'none',
    defaultModelsExpandDepth: -1,
    withCredentials: true
  }
});