NestJS使用Swagger文档

举报
林太白 发表于 2025/05/12 14:24:07 2025/05/12
【摘要】 NestJS使用Swagger文档

nestJS使用Swagger文档

1、安装Swagger相关依赖

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

yarn add @nestjs/swagger swagger-ui-express
fastify:
yarn add @nestjs/swagger fastify-swagger

2. 配置Swagger

main.ts文件中进行Swagger导入SwaggerModuleDocumentBuilder来设置Swagger文档的基本信息。

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'; // 引入swagger文档
 // 配置Swagger文档
 const config = new DocumentBuilder()
 .setTitle('API Documentation') // 设置文档标题
 .setDescription('The API description') // 设置文档描述
 .setVersion('v1.0') // 设置API版本
 .addBearerAuth() // 如果有认证机制可以加上认证
 .build();
// 创建Swagger文档
const document = SwaggerModule.createDocument(app, config);
// 配置Swagger UI,默认访问地址为 /api
SwaggerModule.setup('swagger', app, document);

ok,配置部分非常的简单

3、查看和设置

👉文档地址

打开查看我们的文档地址,我设置的端口号为8888

http://localhost:8888/swagger

这个时候已经可以看到我们的文档了

👉Execute执行查看返回结果

点击执行以后返回结果就会显示到我们这里

👉自定义Swagger配置

使用@ApiProperty()装饰器来描述DTO对象的属性

import { ApiProperty } from '@nestjs/swagger';
export class CreateUserDto {
  @ApiProperty({
    description: 'The name of the user',
    example: 'John Doe',
  })
  username: string;

  @ApiProperty({
    description: '密码必须是6位以及以上',
    example: '123456',
  })
  password: string;
}

👉自定义Get请求参数

请求参数的更改我们前面使用 ApiOperation描述最上面的使用ApiQuery即可

👉自定义post参数示例

@ApiProperty({description: '用户密码(必须是6位及以上)',example: '123456'})

展示的时候

{
  "username": "18735791234",
  "password": "123456"
}

👉定义返回参数

@ApiResponse 装饰器来定义 GET 请求返回参数的含义

export class ResponseUserDto {
  // 定义一个响应数据传输对象
  @ApiProperty({
    description: 'The status code of the response',
    example: 200,
  })
  // 定义响应状态码
  code: number;

  @ApiProperty({
    description: 'The data returned by the API',
    type: [UserDto], // 表示返回的数据是一个 DataDto 数组
  })
  // 定义返回的数据
  data: UserDto[];

  @ApiProperty({
    description: 'The message describing the result',
    example: 'Success',
  })
  // 定义返回的消息
  message: string;
}
// 返回数据的类型
@ApiResponse({
  status: 200,
  description: '成功返回数据',
  type: User, // 指定返回的数据类型
})

到时候给我们返回的案例

{
  "code": 200,
  "data": [
    {
      "username": "18735791234",
      "password": "123456"
    }
  ],
  "message": "查询成功"
}

👉返回参数显示隐藏

用到@Expose()   显示字段以及 @Exclude() 隐藏字段

import { Exclude, Expose } from 'class-transformer';

@Expose()  // 显示字段
@ApiProperty({
  description: '用户密码(必须是6位及以上)',
  example: '123456',
  required: true, // 必填
})
password: string;
required: true; // 必填
@Exclude()  // 隐藏字段
@ApiProperty({
  description: '用户年龄',
  example: 17,
  required: false, // 必填
})
age: number;

服务层过滤

import { UserDto} from '@/common/pipes/user.dto';

async findAll(): Promise<UserDto[]> {
  // 调用userRepository的find方法,返回一个User数组
  // return this.userRepository.find();
  const users = await this.userRepository.find();
  return users.map(user => plainToClass(UserDto, user, { excludeExtraneousValues: true }));
}

这个时候给我们返回的数据

[
  {
    "username": "123",
    "password": "$2b$10$T6B/W5UTcoakCEmlUdW85Suihl8C6jhRi.A6"
  },
  {
    "username": "21323123123",
    "password": "$EumIdh24Dr55QVkhXKbaiMBTuiVo3.bwu"
  },
  {
    "username": "1221112",
    "password": "$2b$10$kHucvS.CyePdwfMzmlUdW85Suihl8C6jhRi.A6"
  }
]
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。