Serverless NestJS: Document your API with Swagger and AWS API Gateway

Add documentation to your API is really important for share it with your team or with your clients, some times the process of create this documentation takes a lot of time and we usually leave it until the end of the project.

I highly recommend to code your API Documentation in the moment that you create the endpoints.

How? With Swagger!

What Is Swagger?

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.

https://swagger.io

So Swagger makes easier the process of documenting your API. We are going to work with Swagger to generate the documentation in our API Gateway in AWS.

I highly recommend you to read my previous article to create your AWS Account and deploy your serverless application to keep working.

NestJS Serverless App with MongoDB Atlas

We are going to use Swagger with NestJS, so here is the documentation to create the documentation. There are so many decorators that we can use to document our serverless application.

This is important because when you create a NestJS Serverless Application unlike pure Javascript Serverless Application, the sls deploy command only creates 1 endpoint /dev/{proxy+}, so this is the reason that motivated me to create this article, we need to document all the endpoints related to our NestJS Serverless Application.

Documentation | NestJS - A progressive Node.js framework

Let’s Get Started!

First we need to add swagger to our application, here is the command:

npm install @nestjs/swagger

So once you have swagger installed (you can check it in your package.json) we need to document our ‘/hello’ endpoint:

We need to make some imports, here is an example:

We are using one decorator here “@ApiResponse()”, this decorator indicates the different responses that our endpoint is going to give us using the GET.

We also need to make some changes in our main.ts file to generate our api endpoint. (We already generated this file in the previous article).

So here is the magic, we need to add this “setupSwagger()” function, this function creates the instance for our API and do all the job. Then we need to modify our handler too. Basically we are redirecting the swagger-ui to /api. This will do all the job to see our api.

Serverless.yml

Obviously we also need to modify our serverles.yml file, we need to add a new section to our file called “custom”, usually this section is used to add some environment variable names and other configurations that we may need to run our application.

custom:
    optimize:
        external: ['swagger-ui-dist']

Be careful, the indent is really important, I highly recommend to use the Prettier plugin if you are coding with Visual Studio.

Your file should look like this:

Let’s Deploy and Test

Now is time to re-deploy our application and launch our api.

sls deploy

If everything goes as expected, you should see your applitacion endpoint. Copy the endpoint and replace /{proxy+} with /api.

https://YOUR-API.execute-api.us-east-1.amazonaws.com/dev/api

Good work! Here is your NestJS Serverless API page, you can click on the endpoints, see the responses and even try the endpoints.

Important: If you click on Try it out is not going to work, this is important because we are deploying our api on dev, so the endpoint should be dev/hello. If you want to try it out on dev, you need to modify the event.path from your main.ts.

Generate API Documentation in AWS API Gateway

We are finally here! Now it’s time to generate our Documentation in AWS API Gateway and share it with our teammates or clients.

Here is the trick, if you go to your API endpoint and add “-json” at the end of it, you are going to receive all your API Swagger Documentation in JSON.

https://YOUR-API.execute-api.us-east-1.amazonaws.com/dev/api-json

So if you copy the JSON and go to Swagger Editor

Swagger Editor

Paste your JSON you will se exactly the same page from your endpoint, here you can modify your Documentation directly but I highly recommend do this on your code.

Here you can download the “.yml” file with all your API Documentation. Click and File and download it.

AWS Console

Finally go to your AWS Console and search for Amazon API Gateway in Services, here you will see all your API information, endpoint, you can change configurations, enable CORS policies and even enable some Authorizers for your API.

Click in Documentation. Here you can manually create all the endpoints for your application with their responses and all the details.

So here is the trick, click on Import Documentation, select the .yml file that you downloaded from the Swagger Editor and then Import it.

Now Publish Documentation, you are ready to share your API Documentation, you can create different Stages for your API. You can share it with your client or teammates as Swagger, API Gateway or even Postman.

There is an option to even generate SDK with your documentation so this AWS tool is just amazing!

So here is the thing, you can automatically generate your API Documentation with NestJS and Swagger and use your JSON file to edit it as you wish and replace it with the API Gateway Documentation, once you are done you can simply comment your Swagger code in your main.ts file and re-deploy your application or if you want deploy your Swagger-ui in production.

Conclusion

The API Documentation is really important for your clients and teammates, you can test it and even have different versions of your documentation as your application grows.

Always take time to document your Application reading the Swagger Documentation and recommendations.

I hope this article helps you documenting your API with AWS in an easy way.

Feel free to contact and connect with me.

Carlos Felipe Villarroel Navarro - IT Manager - Rindegastos | LinkedIn