• Home
  • home > webfront > server > NestJS >

    nestjs使用swagger生成文档：装饰器使用总结

    Author：zhoulujun Date：

    swagg使用起来很简单constapp=awaitNestFactory.create<NestFastifyApplication>(AppModule,newFastifyAdapter(),);constconfig=newDocumen...

    swagg使用起来很简单

    const app = await NestFactory.create<NestFastifyApplication>(
  AppModule,
  new FastifyAdapter(),
);
const config = new DocumentBuilder()
  .setTitle("DataTalk API")
  .setDescription("Open API description")
  .setVersion("1.0.0")
  .addTag("cats")
  .build();
app.setGlobalPrefix("api");
app.enableCors();
app.listen(process.env.PORT ?? 8084);


    以下是 @nestjs/swagger 模块中常用装饰器的详细说明及用法示例，分为 控制器/方法装饰器 和 模型/属性装饰器 两类：

    控制器/方法装饰器

    装饰器用途
    @ApiTags('标签名')给控制器分组（Swagger UI 按标签分类）
    @ApiOperation(options)描述 API 操作（标题、详情等）
    @ApiParam(options)定义路径参数
    @ApiQuery(options)定义查询参数
    @ApiBody(options)定义请求体结构（用于 POST/PUT 请求）
    @ApiResponse(options)定义响应状态码和数据结构
    @ApiHeader(options)定义请求头参数
    @ApiBearerAuth()标记需要 JWT 认证的接口
    控制器示例

    import { Controller, Post, Body, Get, Param } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiBody, ApiParam } from '@nestjs/swagger';
import { CreateUserDto, UserDto } from './dto/user.dto';

@ApiTags('用户')
@Controller('users')
export class UserController {
  @Post()
  @ApiOperation({ summary: '创建用户' })
  @ApiBody({ type: CreateUserDto })
  @ApiResponse({ status: 201, type: UserDto })
  createUser(@Body() dto: CreateUserDto) {
    // ...
  }

  @Get(':id')
  @ApiParam({ name: 'id', type: Number })
  @ApiResponse({ status: 200, type: UserDto })
  getUser(@Param('id') id: number) {
    // ...
  }
}


    模型/属性装饰器

    装饰器用途
    @ApiProperty(options)定义模型属性的元数据（类型、描述等）
    @ApiPropertyOptional()简写 @ApiProperty({ required: false })
    @ApiHideProperty()隐藏属性（不显示在 Swagger 文档）
    @ApiExtraModels(Model)声明额外模型（用于联合类型或多态）
    DTO 模型示例

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

export class CreateUserDto {
  @ApiProperty({ description: '用户名', example: 'Alice' })
  name: string;

  @ApiProperty({ description: '邮箱', format: 'email' })
  email: string;

  @ApiPropertyOptional({ description: '年龄', minimum: 0 })
  age?: number;

  @ApiHideProperty()
  password: string;
}

    联合类型或多态模型

    import { ApiExtraModels, ApiOkResponse, getSchemaPath } from '@nestjs/swagger';

@ApiExtraModels(Cat, Dog)
@Controller()
export class AppController {
  @Get('animals')
  @ApiOkResponse({
    schema: {
      oneOf: [
        { $ref: getSchemaPath(Cat) },
        { $ref: getSchemaPath(Dog) }
      ]
    }
  })
  getAnimals() {
    // ...
  }
}


    与 class-validator 结合：@ApiProperty 可配合 @IsString() 等装饰器使用，同时实现验证和文档生成。





    转载本站文章《nestjs使用swagger生成文档：装饰器使用总结》,
    请注明出处：https://www.zhoulujun.cn/html/webfront/server/nestjs/9535.html

    收藏
    上一篇：class-transformer用法/装饰器总结
    下一篇：最后一页