NestJs配置Swagger及相关配置

安装插件

pnpm add swagger-ui-express
pnpm add @nestjs/swagger -D

配置Swagger

@@filename(swagger.config.ts)
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'

export const swaggerConfig = new DocumentBuilder()
  .setTitle('Swagger Title') // 标题
  .setDescription('Swagger Descripion!') // 描述
  .setVersion('1.0') // 版本
  .build() // 构建

export const createSwaggerDocument = app => {
  // 创建文档
  const document = SwaggerModule.createDocument(app, swaggerConfig)
  // 设置文档
  SwaggerModule.setup('docs', app, document)
}

使用Swagger配置

@@filename(main.ts)
import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'
import { NestExpressApplication } from '@nestjs/platform-express'
import { createSwaggerDocument } from './libs/config/swagger/swagger.config'

/**
 * The bootstrap function is an async function that creates an instance of the Nest application.
 */
async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule)

  createSwaggerDocument(app)

  await app.listen(3000)
}
bootstrap().then(_ => _)

启动项目后访问http://127.0.0.1:3000/docs就可以了

常用属性

方法	描述
setTitle(title: string)	设置文档标题。
setDescription(description: string)	设置文档描述。
setVersion(version: string)	设置文档版本。
setTermsOfService(termsOfService: string)	设置文档服务条款。
setContact(name: string, url: string, email: string)	设置文档联系信息。
setLicense(name: string, url: string)	设置文档许可证信息。
setExternalDoc(description: string, url: string)	设置外部文档链接。
addBearerAuth(options: AddBearerAuthOptions, name: string)	添加 Bearer Token 认证配置。
addApiKey(options: AddApiKeyOptions, name: string)	添加 API Key 认证配置。
addOAuth2(options: AddOAuth2Options, name: string)	添加 OAuth2 认证配置。

常用的Swagger 装饰器

装饰器	描述	使用场景
@ApiTags	为控制器或方法添加标签，用于组织 Swagger UI 文档	标明控制器或方法所属的领域，使文档更易于组织
@ApiOperation	为控制器方法添加操作描述，包括摘要和详细描述	提供关于 API 操作的清晰说明，方便开发者理解 API 的作用
@ApiParam	描述路径参数、请求参数或响应参数，包括名称、类型、描述等	提供详细的参数信息，方便开发者正确使用和理解 API
@ApiBody	指定请求体的 DTO 类型，用于描述请求体的结构	明确请求体的结构，帮助开发者正确发送请求
@ApiResponse	描述 API 的响应，包括状态码、描述等	提供关于 API 响应的详细说明，方便开发者处理各种响应情况
@ApiBearerAuth	指定请求需要携带 Bearer Token，用于身份验证	在需要身份验证的接口中使用，指定需要提供 Token 信息
@ApiProperty	为 DTO 类型的属性添加元数据，如描述、默认值等	提供详细的属性信息，使开发者了解 DTO 对象的结构和约束
@ApiQuery	描述查询参数，包括名称、类型、描述等	用于标识查询参数，使开发者清晰了解 API 的可用查询选项
@ApiHeader	描述请求头信息，包括名称、类型、描述等	提供请求头的详细信息，使开发者正确设置请求头
@ApiExcludeEndpoint	标记一个控制器方法不在 Swagger UI 中显示	在一些特殊情况下，可以使用该装饰器排除不需要在文档中展示的接口

定制Swagger

@ApiTags接口分类

刚配置好的swagger里展示的信息是比较乱的，可以使用@ApiTags()进行分类

import {
  Controller,
  Get,
  Post,
  Body,
  Param,
} from '@nestjs/common'
import { UserService } from './user.service'
import { CreateUserDto } from './dto/create-user.dto'
import { ValidationPipe } from 'src/libs/pipe/validation/validation.pipe'
import { UpdateUserDto } from './dto/update-user.dto'

@ApiTags('app 用户相关')
@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  create(@Body(ValidationPipe) createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto)
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.userService.findOne(id)
  }

  @Post('update')
  update(@Body() updateUserDto: UpdateUserDto) {
    return this.userService.update(updateUserDto)
  }
}

---

@ApiOperation添加描述

...
@ApiOperation({ summary: '创建用户(登录)' })
@Post()
create(@Body(ValidationPipe) createUserDto: CreateUserDto) {
  return this.userService.create(createUserDto)
}
...

---

@ApiParam描述路径参数、请求参数或响应参数，包括名称、类型、描述等

...
@ApiOperation({ summary: '查询用户详情' })
@ApiParam({ type: Number, name: 'id', description: '用户ID' })
@Get(':id')
findOne(@Param('id') id: string) {
  return this.userService.findOne(id)
}
...

---

@ApiBody

...
@ApiOperation({ summary: '更新用户信息' })
@ApiBody({
  type: UpdateUserDto,
  schema: {
    type: 'object',
    items: {
      type: 'string',
      title: 'id',
      default: '12313',
      description: '用户ID'
    }
  }
})
@Post('update')
update(@Body() updateUserDto: UpdateUserDto) {
  return this.userService.update(updateUserDto)
}
...

@ApiBearerAuth设置token

添加addBearerAuth

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

export const swaggerConfig = new DocumentBuilder()
  // 添加 Bearer Token 认证配置
  .addBearerAuth()
  .setTitle('Swagger Title')
  .setDescription('Swagger Descripion!')
  .setVersion('1.0')
  .build()

export const createSwaggerDocument = app => {
  const document = SwaggerModule.createDocument(app, swaggerConfig)
  SwaggerModule.setup('docs', app, document)
}

然后头部会出现一个Authorize的按钮

给需要token的接口设置ApiBearerAuth

import {
  Controller,
  Get,
  Post,
  Body,
  Param,
} from '@nestjs/common'
import { UserService } from './user.service'
import { CreateUserDto } from './dto/create-user.dto'
import { ValidationPipe } from 'src/libs/pipe/validation/validation.pipe'
import { UpdateUserDto } from './dto/update-user.dto'

// 指定需要提供 Token 信息
@ApiBearerAuth()
@ApiTags('app 用户相关')
@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  create(@Body(ValidationPipe) createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto)
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.userService.findOne(id)
  }

  @Post('update')
  update(@Body() updateUserDto: UpdateUserDto) {
    return this.userService.update(updateUserDto)
  }
}

点击Authorize按钮，输入token，再点击弹窗内的Authorize按钮就可以进行接口请求了

---

@ApiProperty

import { ApiProperty } from '@nestjs/swagger'

export class CreateUserDto {
  @ApiProperty({
    name: 'code',
    description: '微信CODE',
    type: String,
    default: ''
  })
    code: string
}