Problem: Frontend developers complained that integration with API is a painful process because there is no documentation on available endpoints, expected payloads and responses. Therefore, our backend team leads elect to enable swagger such that frontend developers can browse all the APIs on dedicated documentation site.
When they showed me how it was done, I was thoroughly impressed and wanted to show NestJS peers the simple steps.
Create a NestJS application
nest new nest-swaggerInstall configuration, swagger and other dependencies
npm install --save @nestjs/config joi class-transformer class-validator
npm install --save @nestjs/swagger swagger-ui-expressStore environment variables in environment file
Store Swagger environment variables in .env and we will use configuration service to retrieve the values in main.ts
// main.ts
NODE_ENV=development
PORT=3000
API_VERSION=1.0
SWAGGER_TITLE=Local Swagger Documentation Site
SWAGGER_DESCRIPITON=The task API descriptionImport Configuration Module and validate schema
// envSchema.ts
import * as Joi from 'joi'
export const validationSchema = Joi.object({
NODE_ENV: Joi.string().valid('development', 'production', 'test', 'provision').default('development'),
PORT: Joi.number().default(3000),
API_VERSION: Joi.string().default('1.0'),
SWAGGER_TITLE: Joi.string().required(),
SWAGGER_DESCRIPITON: Joi.string().required(),
})// app.module.ts
import { Module } from '@nestjs/common'
import { ConfigModule } from '@nestjs/config'
import { AppController } from './app.controller'
import { AppService } from './app.service'
import { validationSchema } from './envSchema'
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
validationSchema,
}),
],
controllers: [AppController],
providers: [AppService],
})
export class AppModule {}Configure Swagger
Initialize Swagger in main.ts such that API documentation is generated automatically for controllers, entities and data transfer objects (DTOs).
// main.ts
async function bootstrap() {
....
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
}),
)
const configService = app.get(ConfigService)
const version = configService.get<string>('API_VERSION', '1.0')
const title = configService.get<string>('SWAGGER_TITLE', '')
const description = configService.get<string>('SWAGGER_DESCRIPITON', '')
const config = new DocumentBuilder()
.setTitle(title)
.setDescription(description)
.setVersion(version)
.addBearerAuth()
.build()
const document = SwaggerModule.createDocument(app, config)
SwaggerModule.setup('api', app, document)
const port = configService.get<number>('PORT', 0)
await app.listen(port)
}Enable Swagger plugin in nest-cli.json
// nest-clis.json
{
"collection": "@nestjs/schematics",
"sourceRoot": "src",
"compilerOptions": {
"plugins": ["@nestjs/swagger"]
}
}After Swagger plugin is enabled, Swagger automatically generates documentation for controller and files with either .entity.s or .dto.ts suffix.
Verify Swagger is working by browsing http://localhost:3000/api
The documentation site works because it publishes the GET endpoint of app controller successfully.
Swagger setup is complete and we can add new API and publish the new endpoints in the dedicated documentation site.
Create a new Task Module to generate API documentation
nest g mo TaskNext, I generate task service and task controller and register them in the TaskModule. The following is the declaration of the TaskModule:
import { Module } from '@nestjs/common'
import { TaskController } from './task.controller'
import { TaskService } from './services'
@Module({
controllers: [TaskController],
providers: [TaskService],
})
export class TaskModule {}Define new entities and new DTOs for Task API
// create-task.dto.ts
import { IsNotEmpty, IsString } from 'class-validator'
export class CreateTaskDto {
@IsNotEmpty()
@IsString()
name: string
}
// update-task.dto.ts
import { IsBoolean, IsDefined } from 'class-validator'
export class UpdateTaskDto {
@IsDefined()
@IsBoolean()
completed: boolean
}Define new entities for the Task API
// task.entity.ts
import { IsBoolean, IsString } from 'class-validator'
export class Task {
@IsString()
id: string
@IsString()
name: string
@IsBoolean()
completed: boolean
}
// delete-result.entity.ts
import { IsNumber, IsOptional, Min, ValidateNested } from 'class-validator'
import { Task } from './task.entity'
export class DeleteResult {
@IsNumber()
@Min(0)
count: number
@IsOptional()
@ValidateNested()
task?: Task
}Create CRUD methods in Task Service
Create basic methods to add, update, delete and retrieve a task object from a tasks array
// task.service.ts
import { BadRequestException, Injectable } from '@nestjs/common'
import { v4 } from 'uuid'
import { CreateTaskDto, UpdateTaskDto } from '../dtos'
import { DeleteResult, Task } from '../entities'
@Injectable()
export class TaskService {
tasks: Task[] = [
...some tasks objects
]
listAll(): Promise<Task[]> {
return Promise.resolve(this.tasks)
}
findById(id: string): Promise<Task> {
const task = this.tasks.find((task) => task.id === id)
if (!task) {
throw new BadRequestException('Task not found')
}
return Promise.resolve(task)
}
deleteById(id: string): Promise<DeleteResult> {
const task = this.tasks.find((task) => task.id === id)
this.tasks = this.tasks.filter((task) => task.id !== id)
const deletedResult: DeleteResult = {
count: task ? 1 : 0,
task,
}
return Promise.resolve(deletedResult)
}
updateTask(id: string, dto: UpdateTaskDto): Promise<Task> {
this.tasks = this.tasks.map((task) => {
if (task.id !== id) {
return task
}
return {
...task,
completed: dto.completed,
}
})
return this.findById(id)
}
createTask(dto: CreateTaskDto): Promise<Task> {
const newTask: Task = {
...dto,
id: v4(),
completed: false,
}
this.tasks = [...this.tasks, newTask]
return Promise.resolve(newTask)
}
}Create endpoints in Task Controller
task.controller.ts
import { UpdateTaskDto } from './dtos/update-task.dto'
import { Body, Controller, Delete, Get, Param, ParseUUIDPipe, Post, Put } from '@nestjs/common'
import { ApiBadRequestResponse, ApiTags } from '@nestjs/swagger'
import { CreateTaskDto } from './dtos'
import { TaskService } from './services'
import { DeleteResult, Task } from './entities'
@ApiTags('Task')
@Controller('task')
export class TaskController {
constructor(private service: TaskService) {}
@Get()
getAll(): Promise<Task[]> {
return this.service.listAll()
}
@Get(':id')
@ApiBadRequestResponse({ description: 'Task not found' })
getTask(@Param('id', ParseUUIDPipe) id: string): Promise<Task> {
return this.service.findById(id)
}
@Delete(':id')
deleteTask(@Param('id', ParseUUIDPipe) id: string): Promise<DeleteResult> {
return this.service.deleteById(id)
}
@Post()
createTask(@Body() dto: CreateTaskDto): Promise<Task> {
return this.service.createTask(dto)
}
@Put(':id')
updateTask(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateTaskDto): Promise<Task> {
return this.service.updateTask(id, dto)
}
}@ApiBadRequestResponse and @ApiBadRequestResponse are Swagger decorators.
| Decorator | Description |
| ApiTags | Provide name of the API and in this example, the name is Task |
| ApiBadRequestResponse | Indicate the endpoint returns BadRequestException when task is not found |
Refresh http://localhost:3000/api and Task API is published.
Task lists all available endpoints (two GETs, POST, DELETE and POST) and Schema section auto-generates its entities (Task and DeleteResult) and DTOs (CreateTaskDto and UpdateTaskDto).
That’s the end of Swagger introduction.
Final thoughts
Swagger provides clear documentation of Restful API that facilitates communication between frontend and backend developers. Rather than constantly asking backend team for sample requests and responses, frontend developers can refer to the Swagger documentation that illustrates all available endpoints and the expected payloads and responses. When teams have no confusion and argument, developers become happy and happy developers are the most productive in application development.
I hope you like this article and share it to people who are interested in NestJS!
Resources:
- Repo: https://github.com/railsstudent/nest-swagger
- OpenAPI (Swagger): https://docs.nestjs.com/openapi/introduction