Swagger UI integration in Express - Mini Project: Build & Apply

Swagger UI integration

📖 Scenario: You are building a simple Express server for a small web service. You want to add interactive API documentation so that users and developers can easily explore your API endpoints.

🎯 Goal: Integrate Swagger UI into your Express server to serve API documentation from a JSON specification file.

📋 What You'll Learn

Create an Express app instance

Add a Swagger JSON specification object

Use the swagger-ui-express middleware to serve the Swagger UI

Mount the Swagger UI at the '/api-docs' route

💡 Why This Matters

🌍 Real World

API documentation is essential for developers to understand and test your web services easily. Swagger UI integration provides a user-friendly interface to explore your API.

💼 Career

Many backend and full-stack developer roles require setting up API documentation. Knowing how to integrate Swagger UI with Express is a valuable skill for building maintainable APIs.

1

Create the Express app

Create a variable called express by requiring the 'express' module. Then create a variable called app by calling express().

Express

const express = require('express');
// Your code here

Need a hint?

Use require('express') to import Express and then call it as a function to create your app.

2

Add the Swagger JSON specification

Create a constant called swaggerDocument and assign it an object with a swagger property set to '2.0', an info object with title 'Sample API' and version '1.0.0', and a paths object with a single path '/hello' that has a get method with a responses object containing a 200 response with a description 'Successful response'.

Express

const express = require('express');
const app = express();

// Create swaggerDocument object here
// Your code here

Need a hint?

Define the Swagger JSON object exactly as described to describe your API.

3

Add swagger-ui-express middleware

Require the swagger-ui-express module into a constant called swaggerUi. Then use app.use to mount swaggerUi.serve and swaggerUi.setup(swaggerDocument) at the route '/api-docs'.

Express

const express = require('express');
const app = express();

const swaggerDocument = {
  swagger: '2.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  },
  paths: {
    '/hello': {
      get: {
        responses: {
          '200': {
            description: 'Successful response'
          }
        }
      }
    }
  }
};

// Require swagger-ui-express and mount middleware at '/api-docs'
// Your code here

Need a hint?

Use require('swagger-ui-express') and app.use to serve the Swagger UI at '/api-docs'.

4

Start the Express server

Add a call to app.listen on port 3000 with a callback function that logs the string 'Server running on port 3000'.

Express

const express = require('express');
const app = express();

const swaggerDocument = {
  swagger: '2.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  },
  paths: {
    '/hello': {
      get: {
        responses: {
          '200': {
            description: 'Successful response'
          }
        }
      }
    }
  }
};

const swaggerUi = require('swagger-ui-express');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// Start server on port 3000
// Your code here

Need a hint?

Use app.listen with a callback to start the server and log a message.