如何在NestJS+GraphQL项目中配置Swagger文档

一、安装依赖 #

首先安装Swagger核心依赖包：

npm install @nestjs/swagger swagger-ui-express

若使用Schema First模式，确保@nestjs/graphql和graphql-tools已完成安装（你已配置好GraphQL，这部分应该已满足）。

二、配置 Swagger 并关联 GraphQL Schema #

在src/main.ts中完成核心配置：

1. 导入必要模块 #

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { GraphQLModule } from '@nestjs/graphql';

2. 初始化应用并关联 GraphQL Schema #

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 获取已配置的GraphQL Schema
  const graphQLSchema = app.get(GraphQLModule).schema;

  // 配置Swagger文档基础元信息
  const config = new DocumentBuilder()
    .setTitle('GraphQL API 文档')
    .setDescription('基于NestJS + GraphQL的接口说明与测试文档')
    .setVersion('1.0')
    .addTag('graphql')
    .build();

  // 创建包含GraphQL Schema的Swagger文档
  const document = SwaggerModule.createDocument(app, config, {
    deepScanRoutes: true,
    transformSchema: (schema) => schema, // 保留原GraphQL Schema结构，可按需自定义转换
  });

  // 将Swagger UI挂载到指定路径（如/api/docs）
  SwaggerModule.setup('api/docs', app, document);

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

三、为 GraphQL 元素添加文档注解 #

根据你的GraphQL开发模式，添加注解增强文档可读性：

Code First 模式 #

在DTO、Resolver类及方法上使用Swagger装饰器：

import { ObjectType, Field, Int } from '@nestjs/graphql';
import { ApiProperty } from '@nestjs/swagger';

@ObjectType()
export class User {
  @Field(() => Int)
  @ApiProperty({ description: '用户唯一ID' })
  id: number;

  @Field()
  @ApiProperty({ description: '用户登录账号' })
  username: string;
}

Resolver方法示例：

import { Query, Resolver } from '@nestjs/graphql';
import { ApiOperation, ApiResponse } from '@nestjs/swagger';
import { User } from './user.dto';

@Resolver(() => User)
export class UserResolver {
  @Query(() => [User])
  @ApiOperation({ summary: '获取全部用户列表' })
  @ApiResponse({ status: 200, description: '成功返回用户数据', type: [User] })
  async getUsers() {
    // 业务逻辑实现
    return [{ id: 1, username: 'demo_user' }];
  }
}

Schema First 模式 #

直接在.graphql文件中添加注释，Swagger会自动识别并展示：

"""
用户基础信息类型
"""
type User {
  """用户唯一标识ID"""
  id: Int!
  """用户登录用户名"""
  username: String!
}

type Query {
  """查询系统全部用户列表"""
  getUsers: [User]!
}

四、访问与测试文档 #

启动应用后，访问http://localhost:3000/api/docs即可进入Swagger UI界面，界面会完整展示你的GraphQL Schema、查询/变更操作，支持直接在界面编写并发送GraphQL请求进行测试。

五、注意事项 #

• 确保@nestjs/graphql与@nestjs/swagger版本兼容，避免依赖冲突；
• 对于联合类型、接口等复杂GraphQL结构，Swagger会自动识别，若展示效果不佳可通过自定义转换逻辑调整；
• 如需修改Swagger UI样式或功能，可在SwaggerModule.setup方法中传入额外配置参数。

内容的提问来源于stack exchange，提问作者mhmadsadikkoliya