Nestjs 学习系列基础篇3 - Swagger 接口文档

参考Swagger官网

Swagger 简介

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。Swagger 遵循了 OpenAPI 规范，OpenAPI 是 Linux 基金会的一个项目，试图通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程。

• Rest API接口的展现
• Rest API测试
• Rest API Mock数据生成

Swagger的使用

在NestJS项目中的使用

1. 安装

   pnpm i @nestjs/swagger
   

2. 在src下创建doc.ts文件

   src/doc.ts

   import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
   import * as packageConfig from '../package.json';
   
   export const generateDocument = (app) => {
     const { name, description, version } = packageConfig;
     // 文档的配置项
     const options = new DocumentBuilder()
       .setTitle(name)
       .setDescription(description)
       .setVersion(version)
       .addBearerAuth() // 增加鉴权功能
       .build();
   
     // 创建文档
     const document = SwaggerModule.createDocument(app, options);
   
     SwaggerModule.setup('/api/doc', app, document);
   };
   

3. 在src/main.ts文件中引入使用

   import { NestFactory } from '@nestjs/core';
   import { AppModule } from './app.module';
   import { generateDocument } from './doc';
   
   async function bootstrap() {
     const app = await NestFactory.create(AppModule);
     // 创建 swagger api 文档
     generateDocument(app);
     await app.listen(3000);
   }
   bootstrap();
   

4. 在src/user/user.controller.ts的基础的使用

   import {
     Controller,
     Get,
     Post,
     Body,
     Patch,
     Param,
     Delete,
     HttpStatus,
   } from '@nestjs/common';
   import { UserService } from './user.service';
   import { CreateUserDto } from './dto/create-user.dto';
   import { UpdateUserDto } from './dto/update-user.dto';
   import {
     ApiBearerAuth,
     ApiOperation,
     ApiResponse,
     ApiTags,
   } from '@nestjs/swagger';
   import { ConfigService } from '@nestjs/config';
   
   @Controller('users')
   @ApiTags('用户管理')
   export class UserController {
     constructor(
       private readonly userService: UserService,
       private readonly configService: ConfigService,
     ) {}
   
     @Post()
     @ApiOperation({
       summary: '新增用户',
     })
     @ApiResponse({
       status: HttpStatus.CREATED,
       type: CreateUserDto,
     })
     @ApiBearerAuth()
     create(@Body() createUserDto: CreateUserDto) {
       return this.userService.create(createUserDto);
     }
   
     @Get()
     @ApiOperation({
       summary: '查询所有用户',
     })
     @ApiResponse({
       status: HttpStatus.CREATED,
       type: CreateUserDto,
     })
     findAll() {
       return this.userService.findAll();
     }
   
     @ApiOperation({
       summary: '查询一个用户',
     })
     @ApiResponse({
       status: HttpStatus.CREATED,
       type: CreateUserDto,
     })
     @Get(':id')
     findOne(@Param('id') id: string) {
       return this.userService.findOne(+id);
     }
   
     @ApiOperation({
       summary: '更新用户信息',
     })
     @ApiResponse({
       status: HttpStatus.CREATED,
       type: CreateUserDto,
     })
     @Patch(':id')
     update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
       return this.userService.update(+id, updateUserDto);
     }
   
     @ApiOperation({
       summary: '删除用户',
     })
     @ApiResponse({
       status: HttpStatus.CREATED,
       type: CreateUserDto,
     })
     @Delete(':id')
     remove(@Param('id') id: string) {
       return this.userService.remove(+id);
     }
   }
   

5. 重新启动项目

   pnpm start
   或者
   pnpm start:dev
   

   在浏览器中输入：http://localhost:3000/api/doc#/

项目仓库地址

仓库地址Github: dome-server

注意：基础篇的的代码在 base 分支下