Documenting your ExpressWebJs API with Swagger
Tags: node, expresswebjs, javascript, swagger
Published: 2021-02-26 14:23:34

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9u09powimhz3p6vzgimu.jpg)

Almost every application today has to be connected to share data with other applications. The best way to do that is through APIs and [ExpressWebjs](https://expresswebjs.com/) is the goto framework for building your node apis.

In this tutorial, however, we’re going to explore Swagger usage along with [expressWebjs](https://expresswebjs.com/).

What is Swagger?
On the Swagger site we can find definition of Swagger:
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

In our example, we’ll be making use of the two libraries: [swagger-ui-express](https://github.com/scottie1984/swagger-ui-express) and [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc).

The first is a module that allows you to feed a Swagger UI (auto-generated views based on the swagger-ui project) from a swagger.json file, or from an inline object.

The second is about integrating Swagger using JSDoc comments in Docs directory in ExpressWebjs. This is pretty useful, especially when you have extensive APIs and dozens of models.

# Application setup

### Install ExpressWebJs

Run the following command in your terminal to create a new project with ExpressWebJs:

```cli
   npx expresswebcli new myNewApp
```

cd into your newly created project.

```cli
   cd myNewApp
```

Visit my article on [developing rest apis with expresswebjs](https://dev.to/alexigbokwe/developing-rest-apis-with-expresswebjs-v2-a-nodejs-framework-part-1-1fg4) or [expresswebjs](https://expresswebjs.com/) documentation for work through on how to get started with expresswebjs.

# Adding swagger
Now that our application is ready, 

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hon1onugip8hurlncq1l.jpeg)

we can now integrate swagger by creating our swagger.json file in the root directory
```js
{
    "definition": {
      "openapi": "3.0.n",
      "info": {
        "title": "My Website API Documentation",
        "version": "0.1.0",
        "description":
          "My website API docs with ExpressWebJs and documented with Swagger",
        "license": {
          "name": "MIT",
          "url": "https://spdx.org/licenses/MIT.html"
        },
        "contact": {
          "name": ""
        }
      },
      "servers": [
        {
          "url": "http://localhost:5100/api"
        }
      ]
    },
    "apis": ["./Docs/*.js"]
  }
```
 This <code>"apis": ["./Docs/*.js"]</code> section specifies the path where your actual documentations are. In our case, it is in Docs folder in the root directory.

After that we can now create our swagger service in App/Service directory.


In App/Service directory, lets create a Swagger folder with an index.js file. Our path will be App/Service/Swagger/index.js

```js
 //App/Service/Swagger/index.js
const swaggerJsdoc = require("swagger-jsdoc");
const swaggerUi = require("swagger-ui-express");
const options = require("../../../swagger.json");

class Swagger{
  static run(){
    let specs = swaggerJsdoc(options);
    serverApp.use("/api-docs",swaggerUi.serve,swaggerUi.setup(specs,{exporer:true}));
  }
}

module.exports = Swagger;
```
# ExpressWebJs ServiceProvider
Next we will register our swagger service in our application service provider. Navigate to App/Providers/AppServiceProvider.js file and add our swagger service to be executed at boot time

```js
 const swagger = require("../Service/swagger");

 class AppServiceProvider {
  /**
   * Register application services.
   */
  register() {
    return {
      //
    };
  }

  /**
   * Bootstrap any application services.
   *
   * @return void
   */
  boot() {
    swagger.run();
  }
}

module.exports = AppServiceProvider;
```

Note: you can create your own service provider. Read more about [ExpressWebjs ServiceProvider in the Documentation site](https://expresswebjs.com/2.0/guide/service-provider.html).

Once all the setup is done, you can now start writing your api documentation in the Docs directory.

To view your swagger docs, run your project using 
```js
  npm run dev
```
and navigate to <code>http://127.0.0.1/api/api-docs</code> in your browser.



### Conclusion
Thank you for reading my article 
You can follow me on twitter [@EmekaIgbokwe](https://twitter.com/EmekaIgbokwe)
You can follow ExpressWebJs on twitter [@expresswebjs](https://twitter.com/expresswebjs)
and don't forget to star on github [ExpressWebJs](https://github.com/Alexigbokwe/ExpressWebJs)

Please, let me know if you have any questions in the comment section. 😊