NestJS 集成 Swagger 详细指引
本指引将手把手教你如何在 NestJS 项目中集成 Swagger,实现自动化 API 文档。
1. 安装依赖
bash
pnpm install @nestjs/swagger
2. 配置环境变量(可选)
在项目根目录下新建 .env
文件,添加如下内容:
env
SWAGGER_PATH=/api-docs
SWAGGER_TITLE=Nest Demo API
SWAGGER_DESCRIPTION=Nest Demo API Documentation
SWAGGER_VERSION=1.0.0
3. 在入口文件中集成 Swagger
编辑 src/main.ts
,添加如下代码:
typescript
import 'dotenv/config';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
// Swagger 配置
const options = new DocumentBuilder()
.setTitle(process.env.SWAGGER_TITLE || 'NestJS API')
.setDescription(process.env.SWAGGER_DESCRIPTION || 'API description')
.setVersion(process.env.SWAGGER_VERSION || '1.0')
.build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup(process.env.SWAGGER_PATH || '/api-docs', app, document);
await app.listen(process.env.PORT ?? 3000);
}
void bootstrap();
4. 可选:为环境变量添加类型提示
在 src/types/env.d.ts
文件中扩展 ProcessEnv
接口:
typescript
declare namespace NodeJS {
interface ProcessEnv {
PORT?: string;
SWAGGER_TITLE?: string;
SWAGGER_DESCRIPTION?: string;
SWAGGER_VERSION?: string;
SWAGGER_PATH?: string;
}
}
确保 tsconfig.json
的 include
包含 src/types
目录。
5. 启动项目并访问文档
bash
npm run start
# 或 pnpm start
访问:http://localhost:3000/api-docs
(或你配置的 SWAGGER_PATH)
6. 常见问题
- 接口未显示?
- 确认控制器和 DTO 上有正确的 Swagger 装饰器(如
@ApiTags
、@ApiProperty
等)。
- 确认控制器和 DTO 上有正确的 Swagger 装饰器(如
- 环境变量无效?
- 确认已安装
dotenv
并在入口文件顶部import 'dotenv/config'
。
- 确认已安装
- 类型提示无效?
- 检查
env.d.ts
文件路径和tsconfig.json
配置。
- 检查
7. 参考文档
如有问题欢迎补充!