The Easiest Way To Start Using Swagger in Node.js

This article will go over what swagger is, why you might want to use it and the easiest way to start using it in your Node.js & Express API.

What is Swagger?

Swagger is a set of tools that a developer can use to make building APIs simpler, I primarily use swagger to document an API however swagger provides tools that aid you in designing, developing, documenting and testing your API. In this article we’ll be focusing on documenting your API.

Why would you want to use Swagger to document your API?

Swagger uses the OpenAPI specification which is considered to be the world standard for RESTful APIs. The swagger tools were built by the team behind the original specification so you know the tools have been built with that specification in mind.

Why is OpenAPI so good?

OpenAPI is a specification that defines a standard which allows humans and machines to easily understand and discover the capabilities of a service without having access to source code, documentation or network traffic, i’m basically writing what’s written in the OpenAPI specification so you should read more about it here

but in short, if you have a complete OpenAPI specification relating to your API you can generate everything else out of that, so you can generate your documentation and you could even generate your source code from this specification, because OpenAPI is language agnostic you can generate source code in various programming languages, although these things are outside the scope of this article.

So what’s the easiest way to add swagger to an existing API?

The easiest way to start using swagger in your Node.js and Express API is to make use of Swagger UI Express. It allows you to serve up docs based on a JSON/YAML file that you provide it.

We’ll need to install swagger-ui-express via NPM

npm install --save swagger-ui-express

Providing you’re using ES6 you then just need to import swagger-ui-express and your swagger definition (we’ll go over how to create this soon), then serve them up from a route of your choosing, in this case we’ll call it api-docs

/* .... */
import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './swagger.json';
app.use('/api-docs', swaggerUi.serve,   swaggerUi.setup(swaggerDocument));
/* ... */

I personally prefer to declare my swagger definition in YAML rather than JSON so at this point I usually install yamljs, but this step is optional.

npm install --save yamljs

I then modify the previous swagger-ui-express setup to look like the following;

/* .... */
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
const swaggerDocument = YAML.load('./swagger.yaml');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
/* .... */

Creating your Swagger definition

The final part to get swagger working is to create your swagger definition, this will be the file that we will then use with swagger-ui-express to generate your documentation from, you can create this in JSON or YAML but for the purpose of this article i’ll be using YAML. Here’s an example swagger definition;

In the above example we can see that we’re specifying OpenAPI version 3.0.0, we’ve got an info section that gives some meta data about our API itself, such as a title, description and version number. We’ve also got a servers section, this is where we specify our different environments such as production, staging, integration and development.

Inside paths is where we start defining out API routes, in this example we’re defining a /users route, we’re saying that we can perform a GET request to this route and that as a result of making that request there should be a 200 HTTP response which will return a JSON payload, the payload itself will be an array of strings.

You can read more about this definition file over on the swagger docs where they go in depth on the specification. This is a good way to get started with swagger as it doesn’t couple your application to anything that isn’t very easy to remove. In reality we’ve only added a couple lines of code and a few modules to your API meaning if you decide that swagger isn’t for you, it doesn’t take a lot to remove it.

Getting more out of Swagger

There are definitely ways to get more out of swagger, like using the Swagger Inspector to inspect your existing API and generate the swagger definition for you based on that, but I think writing your own swagger definition is a good first step as it gives you a better understanding of what OpenAPI is and what’s actually being done for you under the hood.

There is the downside of having to maintain this definition as you work on and extend your API and if you’re working on an API that is constantly changing there are better ways, for example you could allow your definition to live alongside your code by making use of swaggers integration with tools such as jsdoc or you could make use of tools that generate the definition itself such as the inspector mentioned above.

In reality as a developer you really should be maintaining and creating documentation in one form or another wether that’s generating it or writing it, usually for most people they write their documentation and for this group it’s a no brainer to instead write and maintain a specification that can be used to generate documentation and more.

Additional Tools

If you’re looking for a different solution and don’t mind tight coupling you should take a look at Swagger Node which at the cost of being tightly coupled to your code allows you to define your swagger definition with the Swagger Editor meaning you only have to worry about business logic, I wouldn’t recommend this for existing Node.js and Express APIs but if you’re starting something new and are sold on Swagger then go right ahead.

If you’re looking for an easy way to generate stubs for your API you can use Swagger Codegen to achieve this.

In Conclusion

I’ve shown you how to easily add swagger to a Node.js and Express API in a way that allows you to dip your toe without fully committing to the tools. We’ve gone over what the OpenAPI specification is and why you would want to use it. We’ve also touched on how to start writing your own swagger definitions and i’ve also shown you some additional tools that you might want to use. This really is just the start of getting into swagger.