Autogenerated documentation API with OpenAPI and Swagger for NodeJS and Express
Published: 2022-02-15 01:50:15

## 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](https://github.com/OAI/OpenAPI-Specification) for good patterns and [Swagger](https://swagger.io/) for help us to generate the documentation using OpenAPI.

[OpenAPI](https://github.com/OAI/OpenAPI-Specification) 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8ixtrt9j4rc8w3xe2o0g.png)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zcahgp5c5wjcnguy5drf.png)

**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.


![Curl and Post a Person](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/di533np95t3d11aplwle.png)

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