Documenting your ExpressWebJs API with Swagger

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 is the goto framework for building your node apis.

In this tutorial, however, we’re going to explore Swagger usage along with expressWebjs.

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 and 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:

   npx expresswebcli new myNewApp

cd into your newly created project.

   cd myNewApp

Visit my article on developing rest apis with expresswebjs or expresswebjs documentation for work through on how to get started with expresswebjs.

Adding swagger

Now that our application is ready,

we can now integrate swagger by creating our swagger.json file in the root directory

{
    "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 "apis": ["./Docs/*.js"] 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

 //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

 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.

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

  npm run dev

and navigate to http://127.0.0.1/api/api-docs in your browser.

Conclusion

Thank you for reading my article
You can follow me on twitter @EmekaIgbokwe
You can follow ExpressWebJs on twitter @expresswebjs
and don't forget to star on github ExpressWebJs

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