NestJS快速集成Swagger生成API文档
NestJS 中集成 Swagger 自动化生成 API 文档
Swagger 是一个流行的 API 文档工具，能够通过代码注释自动生成交互式文档。NestJS 内置了 @nestjs/swagger 模块，简化了集成过程。
安装依赖包：
npm install @nestjs/swagger
在 main.ts 中初始化 Swagger：
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
const config = new DocumentBuilder()
.setTitle('API 文档')
.setDescription('接口描述')
.setVersion('1.0')
.addTag('cats')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);
使用装饰器定义 API 元数据
通过装饰器为控制器和路由添加描述信息：
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
@ApiTags('cats')
@Controller('cats')
export class CatsController {
@ApiOperation({ summary: '创建猫咪' })
@ApiResponse({ status: 201, description: '创建成功' })
@Post()
create() {
return 'This action adds a new cat';
}
}
定义数据模型 Schema
使用 @ApiProperty 装饰器定义 DTO 类的字段说明：
import { ApiProperty } from '@nestjs/swagger';
export class CreateCatDto {
@ApiProperty({ example: 'Kitty', description: '猫咪名字' })
name: string;
@ApiProperty({ example: 1, description: '猫咪年龄' })
age: number;
}
配置认证选项
为需要认证的接口添加安全配置：
const config = new DocumentBuilder()
.addBearerAuth()
.build();
在控制器方法上添加认证装饰器：
@ApiBearerAuth()
@UseGuards(AuthGuard)
@Get('profile')
getProfile() {
return req.user;
}
生成文档并访问
启动应用后，通过 /api 路径访问 Swagger UI 界面。该界面提供了完整的 API 列表、参数说明和测试功能。
自定义文档配置
通过修改 DocumentBuilder 配置调整文档样式和功能：
const config = new DocumentBuilder()
.setContactEmail('support@example.com')
.setExternalDoc('更多文档', 'https://docs.example.com')
.addServer('https://api.example.com', '生产环境')
.build();
处理枚举和复杂类型
对于枚举或复杂类型，使用 @ApiProperty 的 enum 和 type 参数：
enum Status {
AVAILABLE = 'available',
PENDING = 'pending',
}
@ApiProperty({ enum: Status, enumName: 'Status' })
status: Status;
分组和版本控制
通过创建多个文档实例实现 API 分组：
const v1Doc = new DocumentBuilder().setTitle('API V1').build();
const v2Doc = new DocumentBuilder().setTitle('API V2').build();
SwaggerModule.setup('api/v1', app, SwaggerModule.createDocument(app, v1Doc));
SwaggerModule.setup('api/v2', app, SwaggerModule.createDocument(app, v2Doc));
BbS.okacop081.info/PoSt/1120_602914.HtM
BbS.okacop082.info/PoSt/1120_456050.HtM
BbS.okacop083.info/PoSt/1120_412793.HtM
BbS.okacop084.info/PoSt/1120_594397.HtM
BbS.okacop085.info/PoSt/1120_646983.HtM
BbS.okacop086.info/PoSt/1120_588914.HtM
BbS.okacop087.info/PoSt/1120_104929.HtM
BbS.okacop088.info/PoSt/1120_101044.HtM
BbS.okacop090.info/PoSt/1120_281696.HtM
BbS.okacop091.info/PoSt/1120_798155.HtM
BbS.okacop081.info/PoSt/1120_542815.HtM
BbS.okacop082.info/PoSt/1120_678266.HtM
BbS.okacop083.info/PoSt/1120_174177.HtM
BbS.okacop084.info/PoSt/1120_077688.HtM
BbS.okacop085.info/PoSt/1120_734481.HtM
BbS.okacop086.info/PoSt/1120_903252.HtM
BbS.okacop087.info/PoSt/1120_537502.HtM
BbS.okacop088.info/PoSt/1120_731318.HtM
BbS.okacop090.info/PoSt/1120_312074.HtM
BbS.okacop091.info/PoSt/1120_975578.HtM
BbS.okacop081.info/PoSt/1120_794192.HtM
BbS.okacop082.info/PoSt/1120_173868.HtM
BbS.okacop083.info/PoSt/1120_520011.HtM
BbS.okacop084.info/PoSt/1120_359432.HtM
BbS.okacop085.info/PoSt/1120_469783.HtM
BbS.okacop086.info/PoSt/1120_432686.HtM
BbS.okacop087.info/PoSt/1120_535009.HtM
BbS.okacop088.info/PoSt/1120_507979.HtM
BbS.okacop090.info/PoSt/1120_484855.HtM
BbS.okacop091.info/PoSt/1120_695002.HtM
BbS.okacop081.info/PoSt/1120_180933.HtM
BbS.okacop082.info/PoSt/1120_859497.HtM
BbS.okacop083.info/PoSt/1120_226080.HtM
BbS.okacop084.info/PoSt/1120_322207.HtM
BbS.okacop085.info/PoSt/1120_738165.HtM
BbS.okacop086.info/PoSt/1120_399856.HtM
BbS.okacop087.info/PoSt/1120_645000.HtM
BbS.okacop088.info/PoSt/1120_047418.HtM
BbS.okacop090.info/PoSt/1120_681532.HtM
BbS.okacop091.info/PoSt/1120_020320.HtM
BbS.okacop081.info/PoSt/1120_383514.HtM
BbS.okacop082.info/PoSt/1120_104425.HtM
BbS.okacop083.info/PoSt/1120_131746.HtM
BbS.okacop084.info/PoSt/1120_013212.HtM
BbS.okacop085.info/PoSt/1120_489394.HtM
BbS.okacop086.info/PoSt/1120_083768.HtM
BbS.okacop087.info/PoSt/1120_116535.HtM
BbS.okacop088.info/PoSt/1120_623442.HtM
BbS.okacop090.info/PoSt/1120_751712.HtM
BbS.okacop091.info/PoSt/1120_813064.HtM
BbS.okacop081.info/PoSt/1120_096865.HtM
BbS.okacop082.info/PoSt/1120_439435.HtM
BbS.okacop083.info/PoSt/1120_741144.HtM
BbS.okacop084.info/PoSt/1120_260159.HtM
BbS.okacop085.info/PoSt/1120_401347.HtM
BbS.okacop086.info/PoSt/1120_619538.HtM
BbS.okacop087.info/PoSt/1120_582082.HtM
BbS.okacop088.info/PoSt/1120_652918.HtM
BbS.okacop090.info/PoSt/1120_489380.HtM
BbS.okacop091.info/PoSt/1120_393306.HtM
BbS.okacop081.info/PoSt/1120_011823.HtM
BbS.okacop082.info/PoSt/1120_834933.HtM
BbS.okacop083.info/PoSt/1120_287115.HtM
BbS.okacop084.info/PoSt/1120_329921.HtM
BbS.okacop085.info/PoSt/1120_981115.HtM
BbS.okacop086.info/PoSt/1120_665914.HtM
BbS.okacop087.info/PoSt/1120_689434.HtM
BbS.okacop088.info/PoSt/1120_881770.HtM
BbS.okacop090.info/PoSt/1120_392770.HtM
BbS.okacop091.info/PoSt/1120_425747.HtM
BbS.okacop092.info/PoSt/1120_190387.HtM
BbS.okacop093.info/PoSt/1120_799231.HtM
BbS.okacop094.info/PoSt/1120_908329.HtM
BbS.okacop095.info/PoSt/1120_932360.HtM
BbS.okacop096.info/PoSt/1120_229436.HtM
BbS.okacop097.info/PoSt/1120_545883.HtM
BbS.okacop098.info/PoSt/1120_104272.HtM
BbS.okacop099.info/PoSt/1120_964255.HtM
BbS.okacop114.info/PoSt/1120_591061.HtM
BbS.okacop829.info/PoSt/1120_246423.HtM
