告别手写！Nestjs + Swagger 自动化生成优雅 API 文档

在后端开发中，API 文档的重要性不言而喻。它不仅是前后端联调的桥梁，也是方便其他开发者了解和使用我们服务的关键。传统的手动编写 API 文档方式，不仅耗时耗力，而且容易出现与代码不同步的问题。今天，我们将探讨如何在 Nestjs 项目中使用 Swagger 自动化生成 API 文档，提升开发效率，减少维护成本。尤其在高并发场景下，清晰的文档对于理解接口行为和排查问题至关重要，配合 Nginx 的反向代理和负载均衡，可以更好地支撑服务。

Swagger 简介与 Nestjs 集成原理

Swagger 是一套完整的 API 开发工具集，包括 OpenAPI 规范、Swagger UI、Swagger Editor 等。OpenAPI 规范定义了一种描述 API 接口的标准格式，而 Swagger UI 则可以根据 OpenAPI 规范，自动生成美观易用的 API 文档界面。

在 Nestjs 中集成 Swagger 非常简单，主要依赖于 @nestjs/swagger 模块。该模块提供了一系列的装饰器，用于在代码中描述 API 接口的信息，然后根据这些信息生成 OpenAPI 规范文件，最后通过 Swagger UI 展示出来。其底层原理是通过读取 Nestjs 的 Metadata 信息，解析 Controller 和 DTO 上的装饰器，最终生成符合 OpenAPI 规范的 JSON 或 YAML 文件。

具体代码实现：快速上手 Swagger

首先，我们需要安装 @nestjs/swagger 和 swagger-ui-express 两个依赖包：

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

接下来，在 main.ts 文件中配置 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);

  const config = new DocumentBuilder()
    .setTitle('Cats API') // 设置 API 文档的标题
    .setDescription('The cats API description') // 设置 API 文档的描述
    .setVersion('1.0') // 设置 API 文档的版本
    .addTag('cats') // 添加 API 标签
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document); // 设置 Swagger UI 的访问路径

  await app.listen(3000);
}
bootstrap();

然后在 Controller 中使用 Swagger 提供的装饰器，描述 API 接口的信息：

import { Controller, Get, Post, Body } from '@nestjs/common';
import { ApiOperation, ApiTags, ApiResponse, ApiBody } from '@nestjs/swagger';
import { CreateCatDto } from './dto/create-cat.dto';
import { Cat } from './interfaces/cat.interface';

@ApiTags('cats') // API 分组标签
@Controller('cats')
export class CatsController {
  private readonly cats: Cat[] = [];

  @ApiOperation({ summary: 'Create cat' }) // API 操作描述
  @ApiBody({ type: CreateCatDto }) // 请求体类型
  @ApiResponse({ status: 201, description: 'The record has been successfully created.'}) // 成功响应描述
  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    this.cats.push(createCatDto);
  }

  @ApiOperation({ summary: 'Get all cats' })
  @ApiResponse({ status: 200, description: 'Return all cats.'})
  @Get()
  async findAll(): Promise<Cat[]> {
    return this.cats;
  }
}

最后，定义 DTO (Data Transfer Object) 用于描述请求和响应的数据结构：

import { ApiProperty } from '@nestjs/swagger';

export class CreateCatDto {
  @ApiProperty({ description: '猫的名字' }) // 属性描述
  name: string;

  @ApiProperty({ description: '猫的年龄', example: 3 }) // 属性描述，可以设置示例值
  age: number;

  @ApiProperty({ description: '猫的品种' })
  breed: string;
}

完成以上步骤后，启动 Nestjs 应用，访问 http://localhost:3000/api 即可看到 Swagger UI 自动生成的 API 文档。

实战避坑：常见问题与解决方案

1. DTO 缺失导致 Swagger 文档不完整：确保所有 Controller 中使用的 DTO 都使用了 @ApiProperty 装饰器，否则 Swagger 将无法正确解析数据结构。
2. API 文档与代码不同步： 尽量在开发过程中同步更新 API 文档，或者使用工具自动生成 DTO 和 Controller 的代码。
3. 复杂的类型定义问题：对于复杂的类型，可以使用 @ApiProperty({ type: 'array', items: { type: 'object', properties: { ... } } }) 描述数组类型的对象。
4. Nginx 代理下的 Swagger UI 问题：如果 Nestjs 应用部署在 Nginx 反向代理之后，需要配置 Nginx，确保 Swagger UI 能够正确访问静态资源。

配置 Nginx 的示例：

location /api/ {
  proxy_pass http://localhost:3000/api/;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

location /api/swagger-ui-bundle.js {
  proxy_pass http://localhost:3000/swagger-ui-bundle.js;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

location /api/swagger-ui-init.js {
  proxy_pass http://localhost:3000/swagger-ui-init.js;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

location /api/swagger-ui-standalone-preset.js {
  proxy_pass http://localhost:3000/swagger-ui-standalone-preset.js;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

location /api/swagger-ui.css {
  proxy_pass http://localhost:3000/swagger-ui.css;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

总结

通过 Nestjs 与 Swagger 的集成，我们可以轻松实现 API 文档的自动化生成，提高开发效率，减少维护成本。在实际项目中，需要根据具体的业务场景，灵活运用 Swagger 提供的各种特性，例如 API 分组、权限控制、请求参数校验等。同时，也要注意文档的及时更新，保持与代码的一致性，才能发挥 Swagger 的最大价值。即使面对如 10w+ 这样的高并发连接数，只要文档清晰，就能快速定位问题，提升系统的稳定性。