nest.js提供了两个包用来生成Swagger接口文档，文档用于描述Restful API风格的接口
- 安装两个包
npm install @nestjs/swagger swagger-ui-express
- 在main.ts里进行文档生成配置
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'; async function bootstrap() { const app = await NestFactory.create<NestExpressApplication>(AppModule); app.use(cors()); // 创建接口文档 const options = new DocumentBuilder() // 设置文档标题 .setTitle('Coolboost接口文档') // 设置文档描述 .setDescription('描述======>') // 设置文档版本 .setVersion('1.0') // 创建文档选项 .build(); // 基于app和文档选项生成文档 const document = SwaggerModule.createDocument(app, options); // 定义文档展示路径 SwaggerModule.setup('api-docs',app,document) await app.listen(3000); } bootstrap();
访问localhost:3000/api-docs即可看到文档
常用API
- ApiTags
用于对API进行分组，方便查看
@ApiTags('登录接口')
- ApiOperation
用于描述接口信息，起到提示作用
summary是简要描述，可以直接看到，description是详细描述，需要点开对应标签查看
@ApiOperation({summary: '测试admin',description: '请求该接口需要amdin权限',})
- ApiParam
用于需要传递Param参数的场合，在文档中输入参数后会随请求一起带到接口
第一个参数是传递参数的名称，第二个是传递参数的描述，第三个是参数是否为必填
@ApiParam({ name: 'roles', description: '用户权限', required: true })
- ApiQuery
使用方法和ApiParam类似，唯一不同的是参数将以query的形式进行传递
第一个参数是传递参数的名称，第二个是传递参数的描述，第三个是参数是否为必填
@ApiQuery({ name: 'roles', description: '用户权限', required: true })
- ApiResponse
在文档中写入响应状态，起到提示作用
第一个参数是响应状态码，第二个是描述
@ApiResponse({ status: 403, description: '请求失败' })
- ApiProperty
结合DTO使用，可以起到示例传入参数的作用
import { ApiProperty } from '@nestjs/swagger'; import { IsNotEmpty, IsString, Length, IsNumber } from 'class-validator'; export class CreateLoginDto { // 1 @ApiProperty({example:'诺航同学'}) name: string; // 2 @ApiProperty() age: number; }
如果像1处那样写，文档中的提示为name:诺航同学
如果像2处那样写，文档中的提示为age:string
- ApiBearerAuth
向文档中的特定API添加验证信息，请求头会多带一个token。需要现在main.ts里使用验证
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'; const options = new DocumentBuilder() .setTitle('Coolboost接口文档') .setDescription('描述======>') .addBearerAuth() // 多加这一句 .setVersion('1.0') .build();
接下来在controller中使用即可
import { ApiOperation, ApiTags, ApiParam, ApiQuery, ApiResponse, ApiBearerAuth, } from '@nestjs/swagger'; @ApiTags('登录接口') @ApiBearerAuth() // 在这里使用 @Controller('login') export class LoginController { constructor(private readonly loginService: LoginService) {} @Post() create(@Body() createLoginDto: CreateLoginDto) { return this.loginService.create(createLoginDto); } }
效果如图所示
