API with NestJS #60. The OpenAPI specification and Swagger

NestJS

This entry is part 60 of 85 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.

If you use Fastify, install instead of .

To generate the basics of our Swagger UI, we need to use the and from .

main.ts

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

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

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

Doing all of the above generates the Swagger UI and serves it under at .

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 gives us. To use it, we need to adjust our file and run .

nest-cli.json

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

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 decorator to annotate class properties.

register.dto

The CLI plugin can understand the decorators from the such as

 

Grouping endpoints

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

posts.controller.ts

Describing our endpoints with more details

We can use decorators such as and to provide more details about our endpoints.

posts.controller.ts

Instead of passing and we could use the and 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 endpoint. A lot of its logic happens in the . Therefore, the CLI plugin does not note that the user needs to provide an email and a password. Let’s fix that using the decorator.

authentication.controller.ts

We now can use the “Try it out” button to send a request to the 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 and decorators.

users.controller.ts

fileUpload.dto.ts

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 >>
Subscribe
Notify of
guest
1 Comment
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
wald3
9 months 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]