swagger 补充user 文档

nest-cli.json

@@ -1,4 +1,19 @@
 {
   "collection": "@nestjs/schematics",
-  "sourceRoot": "src"
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name":      "@nestjs/swagger" ,
+        "options": {
+          "dtoFileNameSuffix": [".entity.ts", ".dto.ts"],
+          "controllerFileNameSuffix": [".controller.ts"],
+          "classValidatorShim": true,
+          "introspectComments": true,
+          "dtoKeyOfComment": true,
+          "controllerKeyOfComment": "description"
+        }
+      }
+    ]
+  }
 }

prisma/migrations/20220903161344_add_user_password/migration.sql

@@ -0,0 +1,9 @@
+/*
+  Warnings:
+
+  - Made the column `name` on table `User` required. This step will fail if there are existing NULL values in that column.
+
+*/
+-- AlterTable
+ALTER TABLE "User" ADD COLUMN     "password" TEXT NOT NULL DEFAULT '',
+ALTER COLUMN "name" SET NOT NULL;

prisma/schema.prisma

@@ -10,7 +10,8 @@ datasource db {
 model User {
   id        Int       @id @default(autoincrement())
   email     String    @unique
-  name      String?
+  name      String
+  password  String    @default("")
   createdAt DateTime  @default(now())
   updatedAt DateTime  @updatedAt
   lastLoginAt DateTime @updatedAt @default(now())

src/conifg/swagger.ts

@@ -10,5 +10,7 @@ export function swaggerInit(app: INestApplication) {
     .setDescription(SITE_CONFIG.description)
     .build();
   const document = SwaggerModule.createDocument(app, options);
-  SwaggerModule.setup('api-doc', app, document);
+  SwaggerModule.setup('api-doc', app, document, {
+    explorer: true, // 开启搜索列
+  });
 }

src/decorators/swagger.decorator.ts

@@ -1,6 +1,19 @@
 import { applyDecorators, Type } from '@nestjs/common';
-import { ApiOkResponse, getSchemaPath } from '@nestjs/swagger';
+import { ApiOkResponse, ApiQuery, getSchemaPath } from '@nestjs/swagger';
 import { PaginatedDto } from '../dtos';
+import any = jasmine.any;
+import { ApiCreatedResponse } from '@nestjs/swagger/dist/decorators/api-response.decorator';
+
+export const ApiCreatedSuccessResponse = <TModel extends Type<any>>(
+  model: TModel,
+) => {
+  return applyDecorators(
+    ApiCreatedResponse({
+      description: '返回创建对象',
+      type: model,
+    }),
+  );
+};
 
 export const ApiPaginatedResponse = <TModel extends Type<any>>(
   model: TModel,
@@ -24,5 +37,7 @@ export const ApiPaginatedResponse = <TModel extends Type<any>>(
         ],
       },
     }),
+    ApiQuery({ name: 'limit', example: 20, description: '每页返回数量' }),
+    ApiQuery({ name: 'offset', example: 0, description: '当前偏移位置' }),
   );
 };

src/user/dto/index.dto.ts

@@ -4,6 +4,8 @@ import {
   IsNotEmpty,
   IsNumberString,
   IsString,
+  MaxLength,
+  MinLength,
 } from 'class-validator';
 import { User } from '@prisma/client';
 import { PartialType } from '@nestjs/mapped-types';
@@ -12,29 +14,45 @@ import { ApiProperty, PickType } from '@nestjs/swagger';
 // https://nestjs.bootcss.com/openapi/mapped-types
 
 export class UserDto implements User {
-  @ApiProperty()
   @IsNumberString()
   id: number;
 
-  @ApiProperty()
-  @IsEmail()
-  @IsNotEmpty()
-  email: string;
-
-  @ApiProperty()
+  @ApiProperty({
+    example: 'lambert',
+    description: '用户名',
+  })
   @IsString()
   @IsNotEmpty()
   name: string;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 'l156486648@163.com',
+    description: '用户邮箱',
+  })
+  @IsEmail({
+    message: '邮箱格式不正确',
+  })
+  @IsNotEmpty({
+    message: '邮箱不能为空',
+  })
+  email: string;
+
+  @ApiProperty({
+    example: '12345678',
+    description: '用户密码',
+  })
+  @IsString()
+  @IsNotEmpty()
+  @MinLength(8)
+  @MaxLength(20)
+  password: string;
+
   @IsDateString()
   readonly createdAt: Date;
 
-  @ApiProperty()
   @IsDateString()
   readonly updatedAt: Date;
 
-  @ApiProperty()
   @IsDateString()
   lastLoginAt: Date;
 }
@@ -42,6 +60,7 @@ export class UserDto implements User {
 export class CreateUserDto extends PickType(UserDto, [
   'name',
   'email',
+  'password',
 ] as const) {}
 
 export class UpdateUserDto extends PartialType(CreateUserDto) {}

src/user/user.controller.ts

@@ -7,32 +7,34 @@ import {
   Param,
   Delete,
   Query,
+  Type,
 } from '@nestjs/common';
 import { UserService } from './user.service';
-import { User, Prisma } from '@prisma/client';
+import { Prisma } from '@prisma/client';
 import {
-  ApiBearerAuth,
-  ApiOkResponse,
+  ApiExtraModels,
+  ApiForbiddenResponse,
   ApiOperation,
+  ApiQuery,
   ApiResponse,
   ApiTags,
-  getSchemaPath,
 } from '@nestjs/swagger';
 import { PaginatedDto } from '../dtos';
-import { ApiPaginatedResponse } from '../decorators';
-import { UserDto, UpdateUserDto, CreateUserDto } from './dto/';
+import { ApiCreatedSuccessResponse, ApiPaginatedResponse } from '../decorators';
+import { UserDto, CreateUserDto } from './dto/index.dto';
 
 @ApiTags('用户相关')
 @Controller('users')
+@ApiExtraModels(PaginatedDto)
 export class UserController {
   constructor(private readonly userService: UserService) {}
 
   @Post()
-  @ApiResponse({
-    description: '返回当前创建用户对象',
-    type: UserDto,
-    status: 201,
+  @ApiOperation({
+    summary: '创建用户',
   })
+  @ApiCreatedSuccessResponse(UserDto)
+  @ApiForbiddenResponse({ description: '无操作权限!' })
   create(@Body() createUserDto: CreateUserDto) {
     return this.userService.createUser(createUserDto);
   }
@@ -42,7 +44,6 @@ export class UserController {
   async findAll(
     @Query() limit: number,
     @Query() offset: number,
-    @Query() size: number,
   ): Promise<PaginatedDto<UserDto>> {
     return this.userService.findAll() as any;
   }

src/user/user.service.ts

@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { PrismaService } from '../prisma/prisma.service';
 import { Prisma, User } from '@prisma/client';
-import { CreateUserDto } from './dto';
+import { CreateUserDto } from './dto/index.dto';
 
 @Injectable()
 export class UserService {