安装依赖

pnpm add @nestjs/swagger swagger-ui-express

main.ts配置swagger

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

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  const options = new DocumentBuilder()
    .setTitle('接口文档')
    .setDescription('描述信息')
    .setVersion('1.0.0')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('/apis', app, document);
  await app.listen(3000);
}
bootstrap();

分组

user.controller.ts

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

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  findAll(@Request() res) {
    return {
      code: 200,
      data: res.query.name,
    };
  }
}

添加单个接口描述信息

user.controller.ts

import { ApiTags, ApiOperation } from '@nestjs/swagger';

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  @ApiOperation({ summary: 'get接口', description: '角色' })
  findAll(@Request() res) {
    return {
      code: 200,
      data: res.query.name,
    };
  }
}

接口参数描述

user.controller.ts

import { ApiTags, ApiOperation, ApiParam } from '@nestjs/swagger';

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  @ApiOperation({ summary: 'get接口', description: '角色' })
  findAll(@Request() res) {
    return {
      code: 200,
      data: res.query.name,
    };
  }

  @Get(':id')
  @ApiParam({
    name: 'id',
    description: '获取某个用户by id',
    required: true,
  })
  findOne(@Param('id') id: string) {
    return this.userService.findOne(+id);
  }
}

query参数描述

user.controller.ts

import { ApiTags, ApiOperation, ApiParam, ApiQuery } from '@nestjs/swagger';

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  @ApiOperation({ summary: 'get接口', description: '角色' })
  @ApiQuery({
    name: 'page',
    description: '分页信息',
    required: true,
    type: String,
  })
  findAll(@Request() res) {
    return {
      code: 200,
      data: res.query.name,
    };
  }

  @Get(':id')
  @ApiParam({
    name: 'id',
    description: '获取某个用户by id',
    required: true,
  })
  findOne(@Param('id') id: string) {
    return this.userService.findOne(+id);
  }
}

自定义返回信息

user.controller.ts

import { ApiTags, ApiOperation, ApiParam, ApiQuery, ApiResponse } from '@nestjs/swagger';

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get()
  @ApiOperation({ summary: 'get接口', description: '角色' })
  @ApiQuery({
    name: 'page',
    description: '分页信息',
    required: true,
    type: String,
  })
  @ApiResponse({ status: 200, description: '88' })
  findAll(@Request() res) {
    return {
      code: 200,
      data: res.query.name,
    };
  }

  @Get(':id')
  @ApiParam({
    name: 'id',
    description: '获取某个用户by id',
    required: true,
  })
  findOne(@Param('id') id: string) {
    return this.userService.findOne(+id);
  }
}

post参数装饰

create-user.dto.ts

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

export class CreateUserDto {
  @ApiProperty({ name: 'June', type: String })
  name: string;
  @ApiProperty()
  age: number;
}

user.controller.ts

import { Controller, Get, Param, Request, Post, Body } from '@nestjs/common';
import { UserService } from './user.service';
import {
  ApiTags,
  ApiOperation,
  ApiQuery,
  ApiResponse,
  ApiParam,
  ApiBearerAuth,
} from '@nestjs/swagger';
import { CreateUserDto } from './dto/create-user.dto';

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
@ApiBearerAuth()
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @ApiOperation({ summary: '创建用户', description: '用户' })
  create(@Body() createUserDto: CreateUserDto) {
    return this.userService.create(createUserDto);
  }
}

添加token

main.ts

const options = new DocumentBuilder()
    .addBearerAuth() // 此处添加
    .setTitle('接口文档')
    .setDescription('描述信息')
    .setVersion('1.0.0')
    .build();

user.controller.ts

@Controller({
  path: 'user',
  version: '1',
})
@ApiTags('用户相关接口') // 分组
@ApiBearerAuth()