Autogenerated documentation API with OpenAPI and Swagger for NodeJS and Express

Hi, Devs!

That's really important a documentation and good patterns of our API, it shows in cleanable way what is available.

There are OpenAPI for good patterns and Swagger for help us to generate the documentation using OpenAPI.

OpenAPI is:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

And Swagger can help us to generate the documentation with the good standard from OpenAPI. Look at one example:

We also could execute our routes and get the data through Swagger docs on web. It uses curl to get data from our URL.

A great tool!

So let's see how we can use it. In the root of your project create swagger.js:

const swaggerAutogen = require('swagger-autogen')()

const outputFile = './swagger_output.json'
const endpointsFiles = ['./routers/personRouter.js']

swaggerAutogen(outputFile, endpointsFiles)

The outputFile will have the file configuration about our routes that are executing on Express. The endpointFiles is our path to routes to be documented.

Naturally, after we need to install swagger-autogen and swagger-ui-express.

npm install swagger-autogen and swagger-ui-express

In our package.json we need to add:

  "scripts": {
    "start": "node index.js",
    "swagger-autogen": "node swagger.js"
  },

At the command line in root of our folder we can write and execute:

npm run swagger-autogen

And the swagger_ouput.json will generate. And we can add into the index.js:

const express = require('express');
const swaggerUi = require('swagger-ui-express')
const swaggerFile = require('./swagger_output.json')
const router = require('./routers/personRouter')

const router = express.Router();
const app = express();

app.use(express.json());
app.use('/person', router.personRouter))
app.use('/doc', swaggerUi.serve, swaggerUi.setup(swaggerFile))

app.listen(3000, () => {
  console.log(`Running on 3000`);
});

I'm using personRouter as an example that has some routes, you can use any file that you have the Express routes e references on the swagger.js. At the end you can access:

http://localhost:3000/doc

Use it like a playground.

Save this article, I'm sure that you need to do that in some projects in your life. And if you have any doubt, share on comments.

Contacts
Email: [e-mail]
Instagram: https://www.instagram.com/luizcalaca
Linkedin: https://www.linkedin.com/in/luizcalaca/
Twitter: https://twitter.com/luizcalaca

Comments

[Diogo]

Hi Luiz, how are you? ... to export more endpoints i just need put it inside of array right?

i mean like:
const endpointsFiles = [
'./routes/productsRouter.js',
'./routes/salesRouter.js',
];

[Luiz Calaça]

Certainly, Diogo! Just include all routes into endpointFiles like you wrote.

[Luiz Calaça]

Your example is exactly what is writing on documentation: github.com/davibaltar/swagger-auto...

const outputFile = './path/swagger-output.json';
const endpointsFiles = ['./path/endpointsUser.js', './path/endpointsBook.js'];

/* NOTE: if you use the express Router, you must pass in the
'endpointsFiles' only the root file where the route starts,
such as index.js, app.js, routes.js, ... */

swaggerAutogen(outputFile, endpointsFiles);

[Matheus H.]

This post helped me, thank you Calaça!

[SaTy]

Thanks for sharing!

[Ricardo Sousa]

it's a lot of Pequi in the veins!

[Luiz Calaça]

Hahaha

[Tamir]

Just pointing out if you have somehow swagger.js file in src directory and got routes in src directory as well routes/yourRouteName.js won't work got to add src/routes/yourRouteName.js

[Mugisha Precieux]

is it possible to add request tags ?

[James Prentice]

npm uninstall and

[Ulxn]

const router = require('./routers/personRouter')
const router = express.Router();

I'm sorry, what?!