DEV Community

Cover image for Simplified OpenAPI Docs Using Serverless Framework for Node.js Developers

Posted on • Updated on

Simplified OpenAPI Docs Using Serverless Framework for Node.js Developers


OpenAPI formerly known as swagger docs is a specification. It's a standardised way to describe web APIs using a machine-readable format, typically YAML or JSON. OpenAPI docs could also be written in line as comments in javascript/typescript files. This format outlines the different endpoints, what kind of data they expect (request body), what kind of data they return (response), and other details that are crucial for developers and tools (eg: postman) to understand and interact with your API effectively. 

Serverless framework lets you build and deploy applications without managing servers. You write code for specific functions that execute in response to events (like an API request). The cloud provider handles server provisioning, scaling, and maintenance, allowing you to focus on core functionality and benefit from pay-per-use pricing.

Setting up swagger/OpenAPI with serverless:

Install the following dependencies
npm i swagger-jsdoc with this dependency you will be able to extract swagger doc from comments in javascript files. 

npm i swagger-ui-express this serves interactive swagger ui.

sample swagger ui

Following is a utility function that sets up the swagger configuration, the function accepts express app as the input

sawgger setup with serverless framework

swagger docs extracts the api definitions from the .js files mentioned in the apis array.

swagger and serverless x-forwarded-prefix

Swagger needs the original URL to correctly generate the api documentation, but the api gateway (proxy) modifies the request URL and store a copy of original URL on the "x-forwarded-prefix" header and with this middleware the original URL gets assigned to req.originalUrl.

setting up swagger (openAPI) with serverless framework

A sample swagger doc

Sample swagger doc


final result swagger doc integration with serverless framework

I had trouble setting up swagger docs with AWS and i hope this article helps you out.
Thank you for reading :)


Top comments (2)

ivis1 profile image
Ivan Isaac

This is very informative! Could you please elaborate more on how to handle versioning with OpenAPI in the serverless framework?

abdul_165bf98345e29aea8ef profile image

Thank you for kind words, Yes sure I will write another article on this subject.