Express API with autogenerated OpenAPI doc through Swagger

This post was originally published in the acuriousanimal.com blog.

In past years OpenAPI 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 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

Swagger

Do not confuse OpenAPI with Swagger. 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, writing API docs is not difficult, you only need to write a bunch of YAML lines.

Among other tools, swagger offers the 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:

/**
 * @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: 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: 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.
  

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.

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.