Swagger/OpenAPI specification in Express - Mini Project: Build & Apply

Create a Swagger/OpenAPI Specification for an Express API

📖 Scenario: You are building a simple Express API for a bookstore. You want to create a Swagger/OpenAPI specification to describe your API endpoints so other developers can understand and use your API easily.

🎯 Goal: Build a basic Swagger/OpenAPI specification in JSON format that documents the API with one endpoint /books supporting a GET request.

📋 What You'll Learn

Create a Swagger object with basic info about the API

Add a server URL for the API

Define a GET endpoint /books with a summary and response

Include a response with status 200 and a JSON content type

💡 Why This Matters

🌍 Real World

Swagger/OpenAPI specs help teams document APIs clearly so frontend and backend developers can work together smoothly.

💼 Career

Many companies require API documentation skills for backend or full-stack developer roles to ensure APIs are easy to understand and maintain.

1

Set up the basic Swagger object with API info

Create a variable called swaggerSpec and assign it an object with these exact properties: openapi set to "3.0.0", and info as an object with title set to "Bookstore API" and version set to "1.0.0".

Express

# Create the swaggerSpec object with openapi and info properties
# Your code here

Need a hint?

Use an object with keys openapi and info. The info itself is an object with title and version.

2

Add the server URL to the Swagger specification

Add a property called servers to the swaggerSpec object. It should be an array with one object that has the property url set to "http://localhost:3000".

Express

const swaggerSpec = {
  openapi: "3.0.0",
  info: {
    title: "Bookstore API",
    version: "1.0.0"
  }
};

// Add servers array with url property
# Your code here

Need a hint?

The servers property is an array of objects. Each object has a url string.

3

Define the GET /books endpoint with summary and response

Add a paths property to swaggerSpec. Inside paths, add a /books property. This should have a get property with a summary set to "Get list of books" and a responses object. The responses object should have a "200" property with a description set to "Successful response".

Express

const swaggerSpec = {
  openapi: "3.0.0",
  info: {
    title: "Bookstore API",
    version: "1.0.0"
  },
  servers: [
    {
      url: "http://localhost:3000"
    }
  ]
};

// Add paths with /books GET endpoint, summary, and 200 response
# Your code here

Need a hint?

Use nested objects: paths → /books → get → summary and responses.

4

Add JSON content type to the 200 response

Inside the "200" response object for the GET /books endpoint, add a content property. This should be an object with the key "application/json" set to an empty schema object.

Express

const swaggerSpec = {
  openapi: "3.0.0",
  info: {
    title: "Bookstore API",
    version: "1.0.0"
  },
  servers: [
    {
      url: "http://localhost:3000"
    }
  ],
  paths: {
    "/books": {
      get: {
        summary: "Get list of books",
        responses: {
          "200": {
            description: "Successful response"
          }
        }
      }
    }
  }
};

// Add content with application/json and empty schema to 200 response
# Your code here

Need a hint?

The content property is an object with keys as content types. Each content type has a schema object describing the data.