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