引言
Swagger是一个强大的工具，可以帮助开发者自动生成API文档。在Nest.js项目中集成Swagger，可以大大提升API管理和测试的效率。本篇博客将详细介绍如何在Nest.js项目中集成Swagger，并展示一些高级用法。
安装Swagger
首先，我们需要安装@nestjs/swagger包：
npm install --save @nestjs/swagger
参考文档：Nest.js Swagger文档
在main文件中使用Swagger
接下来，在main.ts文件中设置Swagger配置：
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);
const config = new DocumentBuilder()
.setTitle('接口文档')
.setDescription('描述')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document);
await app.listen(3000, () => {
console.log('127.0.0.1:3000');
});
}
bootstrap();
启动服务
启动Nest.js服务后，访问 http://localhost:3000/docs，你将看到根据代码自动生成的接口文档。
设置标签
使用@ApiTags装饰器为控制器设置标签，以便更好地组织和展示API文档：
import { Controller } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
@ApiTags('用户')
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
}
给每一个请求方法命名
使用@ApiOperation装饰器为每个请求方法添加描述，提高文档的可读性：
import { Post, Body } from '@nestjs/common';
import { ApiOperation } from '@nestjs/swagger';
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Post()
@ApiOperation({ summary: '添加用户' })
create(@Body() createUserDto: CreateUserDto) {
return this.usersService.create(createUserDto);
}
}
添加默认参数
通过创建DTO类并使用@ApiProperty装饰器，可以为请求参数添加描述和默认值，确保API文档更加详细和准确：
import { ApiProperty } from '@nestjs/swagger';
export class CreateUserDto {
@ApiProperty({
description: '邮箱',
})
readonly email: string;
@ApiProperty({
description: '密码',
default: '123456',
})
password: string;
}
自动生成api.json文件并由前端识别
可以通过以下步骤使前端自动识别api.json文件并根据TypeScript自动生成API文件（遵循OpenAPI规范）。
- 生成OpenAPI规范文件
在main.ts中生成并保存OpenAPI规范文件：
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { writeFileSync } from 'fs';
import { join } from 'path';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('接口文档')
.setDescription('描述')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('docs', app, document);
// 保存OpenAPI规范文件
writeFileSync(
join(process.cwd(), 'api.json'),
JSON.stringify(document, null, 2),
);
await app.listen(3000, () => {
console.log('127.0.0.1:3000');
});
}
bootstrap();
- 前端自动生成API文件
前端可以使用工具（如swagger-typescript-api）来自动生成TypeScript API文件。首先，安装swagger-typescript-api：
npm install swagger-typescript-api --save-dev
然后，在前端项目中创建一个脚本来生成API文件：
// generate-api.ts
import { generateApi } from 'swagger-typescript-api';
import * as path from 'path';
async function generate() {
try {
await generateApi({
name: 'api.ts',
output: path.resolve(__dirname, './src/api'),
// 注意这个路径是根据main.js中SwaggerModule.setup如果配置的是docs，那么json就是docs-json，以此类推，如果是api就是api-docs
url: 'http://localhost:3000/docs-json',
});
console.log('API generation completed successfully.');
} catch (error) {
console.error('Error generating API:', error);
}
}
generate();
在package.json中添加一个脚本来运行这个生成脚本：
{
"scripts": {
"generate:api": "ts-node ./src/generate-api.ts",
}
}
现在，你可以运行以下命令来生成API文件：
npm run generate:api
总结
通过本节内容，你学习了如何在Nest.js项目中集成Swagger，从安装配置到高级用法，包括如何正确展示响应体和如何使前端自动识别api.json文件并生成API文件。Swagger的集成使得API文档的生成和维护变得更加轻松、高效，提高了API管理和测试的效率。
