Swagger接口文档

Swagger

Swagger用于给前端提供接口文档，而且每个接口都支持现场测试，官网

安装依赖：

1	npm install @nestjs/swagger swagger-ui-express

注册Swagger

在main.ts注册：

import { NestFactory } from '@nestjs/core';
import { VersioningType } from '@nestjs/common';
import { AppModule } from './app.module';
import { NestExpressApplication } from '@nestjs/platform-express';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
    cors: true,
  });

  // 配置项
  const options = new DocumentBuilder()
    .setTitle('接口文档标题')
    .setDescription('1145141919810')
    .setVersion('1')
    .build();
  // 创建
  const document = SwaggerModule.createDocument(app, options);
  // 初始化
  SwaggerModule.setup('/api-docs', app, document);
  await app.listen(3000);
}
bootstrap();

生成了接口文档：

整理接口文档

添加分组

使用@ApiTags

// ...省略
import { ApiTags } from '@nestjs/swagger';

@ApiTags('守卫')
export class GuardController {
  // ...省略
}

接口描述

使用@ApiOperation描述接口

// ... 省略
import { ApiOperation, ApiTags } from '@nestjs/swagger';

@ApiTags('守卫')
@Controller('guard')
@UseGuards(RoleGuard)
export class GuardController {
  // ...省略
  @Get()
  @Role('admin')
  @ApiOperation({
    summary: '测试admin',
    description: '请求该接口需要admin权限',
  })
  findAll(@ReqUrl('I am data') url: string) {
    console.log(url, 'url');
    return this.guardService.findAll();
  }
  // ...省略
}

Param参数描述

使用@ApiParam描述Param参数

// ...省略
import { ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';

@ApiTags('守卫')
@Controller('guard')
@UseGuards(RoleGuard)
export class GuardController {
  // ...省略
  @Get(':id')
  @ApiParam({ name: 'id', description: '主键', required: true, type: 'number' })
  findOne(@Param('id') id: string) {
    return this.guardService.findOne(+id);
  }
  // ...省略
}

Query参数描述

使用@ApiQuery描述Query参数

// ...省略
import { ApiOperation, ApiParam, ApiQuery, ApiTags } from '@nestjs/swagger';

@ApiTags('守卫')
@Controller('guard')
@UseGuards(RoleGuard)
export class GuardController {
  // ...省略
  @Get()
  @ApiQuery({ name: 'page', description: '分页信息' })
  findAll(@ReqUrl('I am data') url: string) {
    console.log(url, 'url');
    return this.guardService.findAll();
  }
  // ...省略
}

返回信息描述

使用@ApiResponse自定义返回信息

// ...省略
import { ApiOperation, ApiParam, ApiQuery, ApiResponse, ApiTags } from '@nestjs/swagger';

@ApiTags('守卫')
@Controller('guard')
@UseGuards(RoleGuard)
export class GuardController {
  // ...省略
  @Get()
  @ApiResponse({ status: 403, description: '自定义返回信息' })
  findAll(@ReqUrl('I am data') url: string) {
    console.log(url, 'url');
    return this.guardService.findAll();
  }
  // ...省略
}

Post示例描述

使用@ApiProperty描述Post示例

import { ApiProperty } from '@nestjs/swagger';

export class CreateGuardDto {
  @ApiProperty({ example: 'yajue' })
  name: string;
  @ApiProperty({ example: 24 })
  age: number;
}

携带Bearer Token

需要先开启配置：

const options = new DocumentBuilder()
  .addBearerAuth()
  .setTitle('接口文档标题')
  .setDescription('1145141919810')
  .setVersion('1')
  .build();

在Controller中使用，也可以用于单个函数：

// ...省略
import {
  ApiBearerAuth,
  ApiOperation,
  ApiParam,
  ApiQuery,
  ApiResponse,
  ApiTags,
} from '@nestjs/swagger';

@Controller('guard')
@ApiBearerAuth()
export class GuardController {
  // ...省略
}