Annotate API request and response bodies

Author: Aleksi Pekkala

src/api/controllers/PetController.ts

@@ -1,10 +1,34 @@
+import { IsNotEmpty, IsNumber, IsUUID, ValidateNested } from 'class-validator';
 import {
     Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put
 } from 'routing-controllers';
+import { ResponseSchema } from 'routing-controllers-openapi';
 
 import { PetNotFoundError } from '../errors/PetNotFoundError';
 import { Pet } from '../models/Pet';
 import { PetService } from '../services/PetService';
+import { UserResponse } from './UserController';
+
+class BasePet {
+    @IsNotEmpty()
+    public name: string;
+
+    @IsNumber()
+    public age: number;
+}
+
+export class PetResponse extends BasePet {
+    @IsUUID()
+    public id: string;
+
+    @ValidateNested()
+    public user: UserResponse;
+}
+
+class CreatePetBody extends BasePet {
+    @IsUUID()
+    public userId: string;
+}
 
 @Authorized()
 @JsonController('/pets')
@@ -15,23 +39,36 @@ export class PetController {
     ) { }
 
     @Get()
+    @ResponseSchema(PetResponse, { isArray: true })
     public find(): Promise<Pet[]> {
         return this.petService.find();
     }
 
     @Get('/:id')
     @OnUndefined(PetNotFoundError)
+    @ResponseSchema(PetResponse)
     public one(@Param('id') id: string): Promise<Pet | undefined> {
         return this.petService.findOne(id);
     }
 
     @Post()
-    public create(@Body() pet: Pet): Promise<Pet> {
+    @ResponseSchema(PetResponse)
+    public create(@Body({ required: true }) body: CreatePetBody): Promise<Pet> {
+        const pet = new Pet();
+        pet.age = body.age;
+        pet.name = body.name;
+        pet.userId = body.userId;
+
         return this.petService.create(pet);
     }
 
     @Put('/:id')
-    public update(@Param('id') id: string, @Body() pet: Pet): Promise<Pet> {
+    @ResponseSchema(PetResponse)
+    public update(@Param('id') id: string, @Body() body: BasePet): Promise<Pet> {
+        const pet = new Pet();
+        pet.age = body.age;
+        pet.name = body.name;
+
         return this.petService.update(id, pet);
     }
 

src/api/controllers/UserController.ts

@@ -1,10 +1,43 @@
+import { Type } from 'class-transformer';
+import { IsEmail, IsNotEmpty, IsUUID, ValidateNested } from 'class-validator';
 import {
     Authorized, Body, Delete, Get, JsonController, OnUndefined, Param, Post, Put, Req
 } from 'routing-controllers';
+import { ResponseSchema } from 'routing-controllers-openapi';
 
 import { UserNotFoundError } from '../errors/UserNotFoundError';
 import { User } from '../models/User';
 import { UserService } from '../services/UserService';
+import { PetResponse } from './PetController';
+
+class BaseUser {
+    @IsNotEmpty()
+    public firstName: string;
+
+    @IsNotEmpty()
+    public lastName: string;
+
+    @IsEmail()
+    @IsNotEmpty()
+    public email: string;
+
+    @IsNotEmpty()
+    public username: string;
+}
+
+export class UserResponse extends BaseUser {
+    @IsUUID()
+    public id: string;
+
+    @ValidateNested({ each: true })
+    @Type(() => PetResponse)
+    public pets: PetResponse[];
+}
+
+class CreateUserBody extends BaseUser {
+    @IsNotEmpty()
+    public password: string;
+}
 
 @Authorized()
 @JsonController('/users')
@@ -15,28 +48,46 @@ export class UserController {
     ) { }
 
     @Get()
+    @ResponseSchema(UserResponse, { isArray: true })
     public find(): Promise<User[]> {
         return this.userService.find();
     }
 
     @Get('/me')
+    @ResponseSchema(UserResponse, { isArray: true })
     public findMe(@Req() req: any): Promise<User[]> {
         return req.user;
     }
 
     @Get('/:id')
     @OnUndefined(UserNotFoundError)
+    @ResponseSchema(UserResponse)
     public one(@Param('id') id: string): Promise<User | undefined> {
         return this.userService.findOne(id);
     }
 
     @Post()
-    public create(@Body() user: User): Promise<User> {
+    @ResponseSchema(UserResponse)
+    public create(@Body() body: CreateUserBody): Promise<User> {
+        const user = new User();
+        user.email = body.email;
+        user.firstName = body.firstName;
+        user.lastName = body.lastName;
+        user.password = body.password;
+        user.username = body.username;
+
         return this.userService.create(user);
     }
 
     @Put('/:id')
-    public update(@Param('id') id: string, @Body() user: User): Promise<User> {
+    @ResponseSchema(UserResponse)
+    public update(@Param('id') id: string, @Body() body: BaseUser): Promise<User> {
+        const user = new User();
+        user.email = body.email;
+        user.firstName = body.firstName;
+        user.lastName = body.lastName;
+        user.username = body.username;
+
         return this.userService.update(id, user);
     }