Swagger presents a user with the routes in the project, it shows exactly what the shape of the data is and what types of properties are required for each parameter, it lets you know if headers are needed and exactly what kinds they are, if a request body or query param is optional or required, as well as possible HTTP response methods and what each one means. It’s amazing — all that for just three little updates to my Java code.

It seemed like a piece of cake with Spring Boot, and I (naively) thought it would be just as easy to implement Swagger with my full stack, MERN, JavaScript application. Silly me…

Swagger in JavaScript, There’s an NPM Package for that, Right?

Well, the short answer to that question is: yes. The longer answer to that question is: there are many packages. The longest answer is what I’ll tell you now.

Unlike Spring Boot, which has, what could be considered a defacto Swagger package, the world of JavaScript and Swagger is more fractured and fragmented. From my exploration of NPM and the Internet, there didn’t appear to be just one answer to generate Swagger docs and display them in the UI format I’d come to know and love.

So I read some blogs, read some documentation around OpenAPI specification (formerly known as Swagger Specification), and upon learning there was no maintained Swagger docs generator for JavaScript, I ultimately decided I would use Swagger JSDoc to create my Swagger documentation for my routes, and combine it with Swagger UI Express to generate the UI interface in the browser. Let me tell you a bit more about each of these modules.

Swagger JSDoc

Once again, Swagger JSDoc’s own words best describe it:

swagger-jsdoc enables you to integrate Swagger using JSDoc comments in your code. Just add @swagger on top of your DocBlock and declare the meaning of your code in YAML complying to the OpenAPI specification. — Swagger JSDoc, NPM

This means that above each existing API route, you write in your Swagger specs YAML-style (so indentation and colons count) for that route with the @swagger annotation, and this module will then translate that into the UI rendered by my second module: Swagger UI Express.

This module is also especially good for already written APIs (which my project happens to be). I was adding in Swagger documentation as an afterthought — not as part of the initial architecture when I first built the app.

the swagger-jsdoc project assumes that you want document your existing/living/working code in a way to "give life" to it, generating a specification which can then be fed into other Swagger tools, and not the vice-versa.— Swagger JSDoc, NPM

If I had decided to add Swagger earlier in the process, I would have looked at Swagger Editor or Swagger Node.

Swagger UI Express

Swagger UI Express documentation is much less verbose and involved than Swagger JSDoc, because the challenging part really is the writing of the Swagger specifications.

As Swagger UI Express’s docs say, it

Adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app. — Swagger UI Express, NPM

Basically, you follow a prescribed formula to feed the Swagger documentation into the Swagger UI Express module and it generates the HTML UI. And thankfully, the documentation for how to do this is both up to date and accurate. It makes it really simple.

Now that I’ve given a little more background on the two solutions I chose to make Swagger work with JavaScript, and more specifically, my Express/Node.js server application, it’s time to talk about how to implement it.

Let’s Set Up Swagger in JavaScript, How Hard Can it Be?

Once I got the hang of how to write the route specifications, implementing Swagger wasn’t too tough, but to start out with the easiest part, I’ll go over the Swagger UI Express and Swagger JSDoc server setup first.

If you’d like to download my whole project and run it locally or just see the source code, here’s a link to the repo.

Server.js Setup