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

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

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

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

Hint

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

Practice

1. What is the main purpose of using Swagger/OpenAPI specification in an Express app?

easy

A. To speed up the server response time

B. To clearly describe and document the API endpoints and their behavior

C. To automatically fix bugs in the code

D. To encrypt the API data for security

Solution

1. Step 1: Understand Swagger/OpenAPI role

   Swagger/OpenAPI is used to describe APIs so others can understand how to use them.

2. Step 2: Identify main purpose in Express

   It helps document endpoints, request parameters, and responses clearly.

3. Final Answer:

   To clearly describe and document the API endpoints and their behavior -> Option B

4. Quick Check:

   Swagger documents APIs clearly [OK]

Hint: Swagger is for API documentation, not performance or security [OK]

Common Mistakes:

• Thinking Swagger speeds up the server
• Confusing Swagger with security tools
• Assuming Swagger fixes code bugs automatically

2. Which of the following is the correct way to set up swagger-ui-express middleware in an Express app?

easy

A. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

B. app.get('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

C. app.listen('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

D. app.post('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Solution

1. Step 1: Recall Express middleware usage

   Middleware is added with app.use() for routes serving static or UI content.

2. Step 2: Identify swagger-ui-express setup

   swaggerUi.serve and swaggerUi.setup() are passed as middleware to app.use() for '/api-docs'.

3. Final Answer:

   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); -> Option A

4. Quick Check:

   Use app.use for middleware setup [OK]

Hint: Use app.use for middleware, not app.get or app.listen [OK]

Common Mistakes:

• Using app.get instead of app.use for middleware
• Trying to listen on a route path
• Using app.post for serving docs

3. Given this Swagger snippet in an Express app, what HTTP method and path does it describe?

{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create a new user",
        "responses": {
          "201": {"description": "User created"}
        }
      }
    }
  }
}

medium

A. POST request to /users

B. DELETE request to /users

C. PUT request to /users

D. GET request to /users

Solution

1. Step 1: Read the Swagger path and method

   The snippet shows a path '/users' with a 'post' method defined.

2. Step 2: Match HTTP method and path

   The method is POST, and the path is '/users', meaning it creates a new user.

3. Final Answer:

   POST request to /users -> Option A

4. Quick Check:

   Method 'post' means POST request [OK]

Hint: Look for HTTP method keys like 'get', 'post' in paths [OK]

Common Mistakes:

• Confusing 'post' with 'get'
• Ignoring the path and focusing on responses
• Assuming default method is GET

4. You wrote this Swagger setup in your Express app but the docs page shows a blank screen:

import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './swagger.json';

app.use('/docs', swaggerUi.serve, swaggerUi.setup());

What is the likely error?

medium

A. swagger.json file path is incorrect

B. Wrong import syntax for swagger-ui-express

C. Using app.use instead of app.get for docs route

D. Missing swaggerDocument argument in swaggerUi.setup()

Solution

1. Step 1: Check swaggerUi.setup() usage

   swaggerUi.setup() requires the Swagger document as an argument to display docs.

2. Step 2: Identify missing argument

   The code calls swaggerUi.setup() without passing swaggerDocument, so no docs load.

3. Final Answer:

   Missing swaggerDocument argument in swaggerUi.setup() -> Option D

4. Quick Check:

   Always pass Swagger JSON to swaggerUi.setup() [OK]

Hint: Always pass your Swagger JSON to swaggerUi.setup() [OK]

Common Mistakes:

• Forgetting to pass swaggerDocument to setup()
• Using app.get instead of app.use for middleware
• Incorrect import syntax causing silent failure

5. You want to add a new GET endpoint '/products' with a query parameter 'category' described in your Swagger file. Which snippet correctly defines this parameter in OpenAPI 3.0?

hard

A. "parameters": [{"name": "category", "in": "header", "required": false, "schema": {"type": "string"}}]

B. "parameters": [{"name": "category", "in": "path", "required": true, "schema": {"type": "string"}}]

C. "parameters": [{"name": "category", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter products by category"}]

D. "parameters": [{"name": "category", "in": "body", "required": true, "schema": {"type": "string"}}]

Solution

1. Step 1: Identify correct parameter location for query

   Query parameters use "in": "query" and are usually optional.

2. Step 2: Check parameter details

   "parameters": [{"name": "category", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter products by category"}] correctly sets name, in, required false, type string, and description.

3. Final Answer:

   "parameters": [{"name": "category", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter products by category"}] -> Option C

4. Quick Check:

   Query params use "in": "query" [OK]

Hint: Query params use "in": "query", path params use "in": "path" [OK]

Common Mistakes:

• Using "in": "path" for query parameters
• Setting required true for optional query params
• Using "in": "body" which is invalid in OpenAPI 3.0