Nest.js学习之路(26)-用Nestjs Decorator建立Swagger API Doc

在nestjs下可以用相似ASP.net core或者是Java中相似的reflection机制方式，利用Decorators及Swagger Module自动产生API文件页面。

安装套件

yarn add @nestjs/swagger

产生最简单的Swagger API说明页面

在main.ts下，加入产生Swagger页面的代码

async function bootstrap() {    const app = await NestFactory.create(AppModule);    const userApiOptions = new DocumentBuilder()        .setTitle('User API Doc')        .setDescription('User API Info')        .setVersion('1.0')        .addBearerAuth()        .addTag('users') // match tags in controllers        .build();    const userApiDocument = SwaggerModule.createDocument(app, userApiOptions, {include: [UserModule]});    SwaggerModule.setup('v1/api/', app, userApiDocument); await app.listen(3000);}

启动nestjs

2018112401.png

可以看到Parameter底下UserDTO没有相关信息

设定Swagger物件参数

传递物件参数包含@Body、@Query所参考到的物件，如UserDTO、userQueryDTO，要在Swagger页面显示参数信息，通过@ApiModelProperty

userDTO.ts

export class UserDTO {    @ApiModelProperty({        maxLength: 10,        description: 'Username',    })    name: string;    @ApiModelProperty()    age: number;    @ApiModelProperty()    platId: number;    @ApiModelProperty()    plat: Platform;    // @IsNumber({    //  allowNaN: false,    //  allowInfinity: false,    //  }, { each: true, // 检查阵列每一个元素能否都是数字    // })    @ApiModelProperty({required: false})    roleIds: number[];    @ApiModelProperty()    roles: Role[];}

2018112402.png

userQueryDTO

export class UserQueryDTO{    @ApiModelProperty({        description: 'username keyword',    })    @IsString()    name: string;    @ApiModelProperty({        description: 'Page No',        default: 1,    })    @IsNumber()    page: number;    @ApiModelProperty({        description: 'Records Per Page',        default: 5,    })    @IsNumber()    pageSize: number;}

2018112403.png

Http Reponse回传信息

不同Http回应的code显示讯息，通过@ApiOkResponse、@ApiCreatedResponse等来套用在controller下对应的方法，详细@ApixxResponse清单上官网查询

以user.controller为例

@ApiUseTags('users')@ApiBearerAuth()@ApiForbiddenResponse({description: 'Unauthorized'})@UseGuards(AuthGuard())@Controller('user')export class UserController {   constructor(       private readonly userService: UserService,   ) {}   @Post()   // 回传201的形容   @ApiCreatedResponse({description: 'User Created'})   // 回传Internal Error的形容   @ApiInternalServerErrorResponse({description: 'Invalid Input'})   addUser(@Body() userDTO: UserDTO) {       return this.userService.addUser(userDTO);   }   @ApiOkResponse({description: 'Return Users '})   @Get()   getUsers(@Query() query: UserQueryDTO) {       return this.userService.getUsers(query);   }   @Get(':userId')   getUserById(@Param('userId') id) {       return this.userService.getUserById(id);   }   @Delete(':userId')   deleteUser(@Param('userId') id) {       return this.userService.deleteUser(id);   }}

可以根据Exeception Filter显示的message来设定Error类的Response的形容

2018112601.png

以Module来区分Swagger页面

Swagger Module是依据Module来区分页面，现在的专案下，只有UserModule跟AuthModule，可以用不同路径来区分

main.ts

async function bootstrap() {    const app = await NestFactory.create(AppModule);    const userApiOptions = new DocumentBuilder()        .setTitle('User API Doc')        .setDescription('User API Info')        .setVersion('1.0')        .addBearerAuth()        .addTag('users') // match tags in controllers        .build();    const userApiDocument = SwaggerModule.createDocument(app, userApiOptions, {include: [UserModule]});    SwaggerModule.setup('v1/api/user', app, userApiDocument);    const authApiOptions = new DocumentBuilder()            .setTitle('Auth API Doc')            .setDescription('Auth API Info')            .setVersion('1.0')            .addBearerAuth()            .addTag('auth') // match tags in controllers                        .build();    const authApiDocument = SwaggerModule.createDocument(app, authApiOptions, {include: [AuthModule]});    SwaggerModule.setup('v1/api/auth', app, authApiDocument); await app.listen(3000);}bootstrap();

2018112602.png

Auth API独立另外一个页面

推荐一下我的公众号: 【 geekjc 】，微信号: 【 c8706288 】一起学习交流编程知识，分享经验，各种有趣的事。

tuiguang.png