Express API with autogenerated OpenAPI doc through Swagger
Tags: node, express, swagger, api
Published: 2018-11-09 07:31:00

---
title: 'Express API with autogenerated OpenAPI doc through Swagger'
published: true
date: 2018-11-09 07:31
tags: 
- nodejs
- express
- swagger
- api
cover_image: https://cdn-images-1.medium.com/max/2000/1*K2pgiswC1Q3Z_8o3N9vcdg.png
---

> This post was originally published in the [acuriousanimal.com blog](http://www.acuriousanimal.com/2018/10/20/express-swagger-doc.html).

In past years [OpenAPI](https://www.openapis.org) has arise as the preferred way to document APIs. In this article we will see how easy is document an API created with NodeJS and Express through the [Swagger](https://swagger.io/) tools.

If you are working in an REST API you more probably will desire to have some API doc where your users could find what are the endpoints of your API, what they do, which parameters they accept and which output they generate.

> See accelerated video at: [https://www.youtube.com/watch?v=CE01dwNEkEU](https://www.youtube.com/watch?v=CE01dwNEkEU)


## Swagger

[Do not confuse OpenAPI with Swagger](https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/). OpenAPI is an specification that says how APIs are documented. Swagger is a collection of tools to implement the specification.

Thanks to Swagger, see the [editor example](https://editor.swagger.io/), writing API docs is not difficult, you only need to write a bunch of YAML lines.

Among other tools, swagger offers the [swagger-ui](https://github.com/swagger-api/swagger-ui), which is nothing more than *a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API*, or in other words, `swagger-ui` is the beautiful web page ou see in the previous swagger editor link.

To serve the `swagger-ui` content you only need a web server and the API documentation bundled in a JSON or YAML file.

## ExpressJS and API documentation

When developing APIs with ExpressJS I tend to write my API endpoints in *route* files (usually also stored under a `routes` folder) which contains the rules to attend requests and, because of this, it is a perfect location to document the endpoints of my API, for example:

```javascript
/**
 * @swagger
 * /users:
 *    get:
 *      description: This should return all users
 */
app.get('/users', (req, res) => res.end('This sould return all users'));
```

The problem is `swagger-ui` requires all my API doc reside in a single file, i.e. `swagger.json`, to be beautified as a web page.

## How to autogenerate swagger doc ?

All the magic resides in the next packages:

- [swagger-ui-express](https://github.com/scottie1984/swagger-ui-express): 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-jsdoc](https://github.com/Surnet/swagger-jsdoc): Generates swagger doc based on JSDoc comments in your code to keep a live and reusable OpenAPI (Swagger) specification.

So the idea is:

- Document your routes with jsdoc using the swagger YAML notation (as you can see in the previous route).

- Let `swagger-jsdoc` to autogenerate a `swagger.json` file with all the documentation you set in your files.

```javascript
const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  swaggerDefinition: {
    // Like the one described here: https://swagger.io/specification/#infoObject
    info: {
      title: 'Test API',
      version: '1.0.0',
      description: 'Test Express API with autogenerated swagger doc',
    },
  },
  // List of files to be processes. You can also set globs './routes/*.js'
  apis: ['endpoints.js'],
};

const specs = swaggerJsdoc(options);
```

- Use the `swagger-ui-express` to add a new endpoint where your user can see the documentation.

```javascript
const swaggerUi = require('swagger-ui-express');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
```

That is all the magic. At this point if you start and open your browser at `http://localhost:3000/api-docs` you will see the Swagger UI web page with the documentation of your endpoint.

Of course you can create much more complex documentations. You can include files which only defines includes type definitions (i.e. about input/output data), group your endpoints by tags, etc.

The important thing is how the convination of `swagger-ui-express` and `swagger-jsdoc` can incredible help and simplify the way to have your API documentation always up to date.