DEV Community

Cover image for Autogenerated documentation API with OpenAPI and Swagger for NodeJS and Express
Luiz Calaça
Luiz Calaça

Posted on • Updated on

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:

Swagger and OpenAPI

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

Swagger running routes

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

In our package.json we need to add:

  "scripts": {
    "start": "node index.js",
    "swagger-autogen": "node swagger.js"
  },
Enter fullscreen mode Exit fullscreen mode

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

npm run swagger-autogen
Enter fullscreen mode Exit fullscreen mode

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`);
});

Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Use it like a playground.

Curl and Post a Person

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: luizcalaca@gmail.com
Instagram: https://www.instagram.com/luizcalaca
Linkedin: https://www.linkedin.com/in/luizcalaca/
Twitter: https://twitter.com/luizcalaca

Top comments (11)

Collapse
 
ogoiddev profile image
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',
];

Collapse
 
luizcalaca profile image
Luiz Calaça

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

Collapse
 
luizcalaca profile image
Luiz Calaça • Edited

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);

Collapse
 
ymaatheus profile image
Matheus H.

This post helped me, thank you Calaça!

Collapse
 
mengtongun profile image
SaTy

Thanks for sharing!

Collapse
 
ricardosousadev profile image
Ricardo Sousa

it's a lot of Pequi in the veins!

Collapse
 
luizcalaca profile image
Luiz Calaça

Hahaha

Collapse
 
tamirazrab profile image
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

Collapse
 
mugishap profile image
Mugisha Precieux

is it possible to add request tags ?

Collapse
 
jamesprenticez profile image
James Prentice

npm uninstall and

Collapse
 
enganese profile image
Ulxn

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

I'm sorry, what?!