Body, Query and Params ​

The SwaggerModule searches for all @Body() and @Query() decorators in route handlers to generate the API document. It also creates corresponding model definitions by taking advantage of reflection. Consider the following code:

@Post()
async create(@Body() createTodoDto: CreateTodoDto) {
  this.todoService.create(createTodoDto);
}

Based on the Todo, the following model definition Swagger UI will be created:

In order to make the class properties visible to the SwaggerModule, we have to annotate them with the @ApiProperty() decorator :

export class CreateTodoDto {
  @ApiProperty()
  name!: string;

  @ApiProperty()
  priority!: number;

  @ApiProperty()
  colorLabel!: string;
}

Let's open the browser and verify the generated Todo model:

Return type ​

There are multiple ways to define the return type of a route.

The easiest way is to type your method.

The SwaggerModule will automatically detect the return type of a route handler and generate the corresponding model definition if it's not an array. The following code will generate a model definition for the Todo class as Danet understands that the getById method returns a Todo object:

@Get(':id')
  async getById(@Param('id') id: string): Todo {
    return this.todoService.getById(id);
  }

When it's an array, or if you don't want to type your method for some (obscure) reasons, you can also use the @ReturnedType decorator to explicitly set the return type of a route handler.

@ReturnedType(Todo)
@Get(':id')
async getById(@Param('id') id: string): Todo {
  return this.todoService.getById(id);
}

If your route returns an array, pass true as the second argument of ReturnedType :

@ReturnedType(Todo, true)
@Get()
async getTodos(): Todo[] {
  return this.todoService.getAll();
}

Enums ​

To identify an enum, we must manually set the enum property on the @ApiProperty with an array of values.

@ApiProperty({ enum: ['Admin', 'Moderator', 'User']})
role: UserRole;

Zod ​

The OpenAPI module also supports Zod schemas. You can find more information on the dedicated page here.