API with NestJS #60. The OpenAPI specification and Swagger

February 14, 2022

This entry is part 60 of 175 in the API with NestJS

Across this series, we emphasize code readability and maintainability. In part #52 of this course, we’ve gone through generating documentation with Compodoc and JSDoc. This time we look into the OpenAPI specification and the Swagger tool.

You can check out an interactive demo prepared by the Swagger team.

Introducing OpenAPI and Swagger

With OpenAPI and Swagger, we can create a user interface that serves as interactive API documentation for our project. However, since it might be confusing, it is worth outlining the difference between the OpenAPI and the Swagger.

The OpenAPI is a specification used to describe our API and gives us a way to provide the details of our endpoints. It includes the endpoints and the description of each operation’s inputs and outputs. It also allows us to specify our authentication method, license, and contact information.

Swagger is a set of tools built around the OpenAPI specification. The one that we present in this article is the Swagger UI. It allows us to render the OpenAPI specification we wrote in as the API documentation. The thing that makes it so valuable is that it is interactive. Swagger generates a web page that we can publish so that people can view our API and make HTTP requests. It is a great tool to share knowledge with other people working in our organization. If our API is open to the public, we can also deploy the above page and share it with everyone.

OpenAPI Specification was formerly called the Swagger Specification, which might add more to the confusion.

Adding Swagger to our NestJS project

We need to install two dependencies to add Swagger to our NestJS project.

1	npm install @nestjs/swagger swagger-ui-express

If you use Fastify, install fastify-swagger instead of swagger-ui-express.

To generate the basics of our Swagger UI, we need to use the SwaggerModule and DocumentBuilder from @nestjs/swagger.

main.ts

import { NestFactory } from '@nestjs/core';

import { AppModule } from './app.module';

import { ConfigService } from '@nestjs/config';

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {

const app = await NestFactory.create(AppModule);

const configService = app.get(ConfigService);

// ...

const swaggerConfig = new DocumentBuilder()

.setTitle('API with NestJS')

.setDescription('API developed throughout the API with NestJS course')

.setVersion('1.0')

.build();

const document = SwaggerModule.createDocument(app, swaggerConfig);

SwaggerModule.setup('api', app, document);

const port = configService.get('PORT') ?? 3000;

await app.listen(port);

}

bootstrap();

The DocumentBuilder class contains a set of methods we can use to configure our Swagger UI.

Besides the above functions such as the setTitle, we will also go through some of the others in this article.

@nestjs/swagger/dist/document-builder.d.ts

export declare class DocumentBuilder {

private readonly logger;

private readonly document;

setTitle(title: string): this;

setDescription(description: string): this;

setVersion(version: string): this;

setTermsOfService(termsOfService: string): this;

setContact(name: string, url: string, email: string): this;

setLicense(name: string, url: string): this;

addServer(url: string, description?: string, variables?: Record<string, ServerVariableObject>): this;

setExternalDoc(description: string, url: string): this;

setBasePath(path: string): this;

addTag(name: string, description?: string, externalDocs?: ExternalDocumentationObject): this;

addSecurity(name: string, options: SecuritySchemeObject): this;

addSecurityRequirements(name: string | SecurityRequirementObject, requirements?: string[]): this;

addBearerAuth(options?: SecuritySchemeObject, name?: string): this;

addOAuth2(options?: SecuritySchemeObject, name?: string): this;

addApiKey(options?: SecuritySchemeObject, name?: string): this;

addBasicAuth(options?: SecuritySchemeObject, name?: string): this;

addCookieAuth(cookieName?: string, options?: SecuritySchemeObject, securityName?: string): this;

build(): Omit<OpenAPIObject, 'paths'>;

}

Doing all of the above generates the Swagger UI and serves it under at http://localhost:3000/api.

The above URL might be different based on the port of your NestJS application.

Generating our OpenAPI specification automatically

Unfortunately, the specification we’ve defined so far does not contain much detail.

We can help NestJS generate a more detailed OpenAPI specification out of the box. To do that, we need to use the CLI plugin "@nestjs/swagger" gives us. To use it, we need to adjust our nest-cli.json file and run nest start.

nest-cli.json

{

"collection": "@nestjs/schematics",

"sourceRoot": "src",

"compilerOptions": {

"plugins": ["@nestjs/swagger"]

}

The CLI plugin assumes that our DTOs are suffixed with .dto.ts or .entity.ts. It also assumes that the files that contain controllers end with .controller.ts.

Defining the OpenAPI specification manually

Thanks to using the above solution, we automatically get a significant part of the specification generated. If we want to make some changes, we can use the wide variety of decorators that NestJS gives us.

Models definition

We can use the @ApiProperty() decorator to annotate class properties.

register.dto

import { IsEmail, IsString, IsNotEmpty, MinLength, Matches } from 'class-validator';

import { ApiProperty } from '@nestjs/swagger';

export class RegisterDto {

@IsEmail()

email: string;

@IsString()

@IsNotEmpty()

name: string;

@ApiProperty({

deprecated: true,

description: 'Use the name property instead'

})

fullName: string;

@IsString()

@IsNotEmpty()

@MinLength(7)

password: string;

@ApiProperty({

description: 'Has to match a regular expression: /^\\+[1-9]\\d{1,14}$/',

example: '+123123123123'

})

@IsString()

@IsNotEmpty()

@Matches(/^\+[1-9]\d{1,14}$/)

phoneNumber: string;

}

export default RegisterDto;

The CLI plugin can understand the decorators from the class-validator such as @MinLength()

Grouping endpoints

All of our endpoints go into the “default” group by default. To categorize them better, we can use the @ApiTags() decorator.

posts.controller.ts

import {

Controller,

} from '@nestjs/common';

import PostsService from './posts.service';

import { ApiTags } from '@nestjs/swagger';

@Controller('posts')

@ApiTags('posts')

export default class PostsController {

constructor(

private readonly postsService: PostsService

) {}

// ...

}

Describing our endpoints with more details

We can use decorators such as @ApiParam() and @ApiResponse() to provide more details about our endpoints.

posts.controller.ts

@Get(':id')

@ApiParam({

name: 'id',

required: true,

description: 'Should be an id of a post that exists in the database',

type: Number

})

@ApiResponse({

status: 200,

description: 'A post has been successfully fetched',

type: PostEntity

})

@ApiResponse({

status: 404,

description: 'A post with given id does not exist.'

})

getPostById(@Param() { id }: FindOneParams) {

return this.postsService.getPostById(Number(id));

}

Instead of passing status: 200 and status: 404 we could use the @ApiOkResponse() and @ApiNotFoundResponse() decorators.

Authenticating with cookies

In this series, we use cookie-based authentication. Since many of our endpoints require the user to log in, let’s add this functionality to our OpenAPI specification.

If you want to know more about authentication, check out API with NestJS #3. Authenticating users with bcrypt, Passport, JWT, and cookies

Swagger supports a variety of different types of authentication. Unfortunately, it currently does not support sending cookies when using the “Try it out” button. We can deal with this issue by using the Swagger interface to directly log in to our API.

In our application, we have the /log-in endpoint. A lot of its logic happens in the LocalAuthenticationGuard. Therefore, the CLI plugin does not note that the user needs to provide an email and a password. Let’s fix that using the @ApiBody() decorator.

authentication.controller.ts

@HttpCode(200)

@UseGuards(LocalAuthenticationGuard)

@Post('log-in')

@ApiBody({ type: LogInDto })

async logIn(@Req() request: RequestWithUser) {

const { user } = request;

const accessTokenCookie = this.authenticationService.getCookieWithJwtAccessToken(user.id);

const {

cookie: refreshTokenCookie,

token: refreshToken

} = this.authenticationService.getCookieWithJwtRefreshToken(user.id);

await this.usersService.setCurrentRefreshToken(refreshToken, user.id);

request.res.setHeader('Set-Cookie', [accessTokenCookie, refreshTokenCookie]);

if (user.isTwoFactorAuthenticationEnabled) {

return;

}

return user;

}

We now can use the “Try it out” button to send a request to the /log-in endpoint.

Performing the above request sets the right cookie in our browser. Thanks to that, we will send this cookie when interacting with other endpoints automatically.

Handling file uploads

In part #55 of this series, we’ve implemented a way to upload files and store them on our server. To reflect that in Swagger, we can use the @ApiBody() and @ApiConsumes() decorators.

users.controller.ts

import { UsersService } from './users.service';

import { BadRequestException, Controller, Post, Req, UploadedFile, UseGuards, UseInterceptors } from '@nestjs/common';

import JwtAuthenticationGuard from '../authentication/jwt-authentication.guard';

import RequestWithUser from '../authentication/requestWithUser.interface';

import { Express } from 'express';

import LocalFilesInterceptor from '../localFiles/localFiles.interceptor';

import { ApiBody, ApiConsumes } from '@nestjs/swagger';

import FileUploadDto from './dto/fileUpload.dto';

@Controller('users')

export class UsersController {

constructor(

private readonly usersService: UsersService,

) {}

@Post('avatar')

@UseGuards(JwtAuthenticationGuard)

@UseInterceptors(LocalFilesInterceptor({

fieldName: 'file',

path: '/avatars',

fileFilter: (request, file, callback) => {

if (!file.mimetype.includes('image')) {

return callback(new BadRequestException('Provide a valid image'), false);

}

callback(null, true);

limits: {

fileSize: Math.pow(1024, 2) // 1MB

}

}))

@ApiConsumes('multipart/form-data')

@ApiBody({

description: 'A new avatar for the user',

type: FileUploadDto,

})

async addAvatar(@Req() request: RequestWithUser, @UploadedFile() file: Express.Multer.File) {

return this.usersService.addAvatar(request.user.id, {

path: file.path,

filename: file.originalname,

mimetype: file.mimetype

});

}

fileUpload.dto.ts

import { ApiProperty } from '@nestjs/swagger';

import { Express } from 'express';

class FileUploadDto {

@ApiProperty({ type: 'string', format: 'binary' })

file: Express.Multer.File;

}

export default FileUploadDto;

Doing the above creates an interface in Swagger UI where we can upload our image.

Summary

We’ve gone through the OpenAPI specification and the Swagger UI tool in this article. We’ve used the CLI plugin to get a lot out of the box. Still, there were some cases that we had to cover manually using different decorators that NestJS gives us. We’ve also dealt with cookie authentication and file uploads. The above gave us the necessary knowledge to create robust, interactive documentation.

Series Navigation<< API with NestJS #59. Introduction to a monorepo with Lerna and Yarn workspacesAPI with NestJS #61. Dealing with circular dependencies >>

1 Comment

Oldest

Newest Most Voted

Inline Feedbacks

View all comments

wald3

2 years ago

Thank you, as always, you provided the information competently!

It would be nice to notice one more thing – Authorization. Swagger provides us with some simple extensions and decorators for authentication. For example, passing JWT tokens – by adding .addBearerAuth() to a swagger-document we are adding an input token input field on Swagger UI, that token will be inserted as auth header(Authorization: Bearer <our-token>) and we also need to add @ApiBearerAuth(), decorator, to our route or controller, we can add multiple Auth strategies, and separate them with a name.

To know more security scenarios I recommend checking those links:
[Security NestJs docs] [SO – Swagger Auth Options question]