Swagger/OpenAPI specification in Express - Step-by-Step Execution

Concept Flow - Swagger/OpenAPI specification

Write API spec in YAML/JSON

↓

Load spec in Express app

↓

Use swagger-ui middleware

↓

Serve interactive API docs

↓

User tests API via docs

↓

API responds as defined

The flow shows how you write an API description, load it in Express, serve docs, and users interact with the API.

Execution Sample

Express

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

This code loads a Swagger JSON file and sets up the Express route to serve interactive API docs.

Execution Table

Step	Action	Input/State	Output/Result
1	Load swagger.json file	File swagger.json with API spec	swaggerDocument object with API details
2	Call app.use with /api-docs	Express app instance	Middleware registered to serve docs
3	User visits /api-docs URL	HTTP GET /api-docs	Swagger UI HTML page served
4	User views API endpoints	Swagger UI renders from swaggerDocument	Interactive API docs visible
5	User tries an API call via docs	User clicks 'Try it out'	API request sent, response shown
6	API responds	Request received by Express routes	Response data shown in docs
7	End	No further action	User can explore or close docs

💡 User finishes exploring or closes the API docs page

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
swaggerDocument	undefined	Loaded JSON object	Loaded JSON object	Loaded JSON object	Loaded JSON object
Express app middleware	none	none	swagger-ui middleware registered	middleware active	middleware active

Key Moments - 3 Insights

Why do we need to load the swagger.json file before using swagger-ui-express?

Because swagger-ui-express uses the loaded API spec object to generate the interactive docs, as shown in execution_table step 1 and 2.

What happens when a user visits the /api-docs route?

The middleware serves the Swagger UI HTML page that renders the API docs from the swaggerDocument, as seen in execution_table step 3 and 4.

How does the 'Try it out' feature in Swagger UI work?

It sends real API requests to the Express routes and shows responses, connecting the docs to the actual API, shown in steps 5 and 6.

Visual Quiz - 3 Questions

Look at the execution_table, what is the state of swaggerDocument after step 1?

A It is an object containing the API specification

B It is undefined

C It is a string with the file path

D It is the Express app instance

💡 Hint

Check the 'Output/Result' column in step 1 of execution_table

At which step does the user receive the interactive API documentation page?

A Step 5

B Step 2

C Step 3

D Step 6

💡 Hint

Look at the 'Output/Result' column for step 3 in execution_table

If the swagger.json file is missing, what will happen at step 1?

A Middleware will still register normally

B swaggerDocument will be undefined or error occurs

C User will see API docs anyway

D Express app will crash at step 3

💡 Hint

Refer to variable_tracker for swaggerDocument initial loading state

Concept Snapshot

Swagger/OpenAPI spec describes your API in JSON/YAML.
Load this spec in Express using swagger-ui-express middleware.
Serve docs at a route like /api-docs.
Users see interactive docs and can test API calls.
Docs reflect your API routes and responses.
Keep spec updated for accurate docs.

Full Transcript

This visual execution shows how to use Swagger/OpenAPI specification with Express. First, you write your API description in a swagger.json file. Then, you load this file into your Express app as an object called swaggerDocument. Next, you use the swagger-ui-express middleware to serve interactive API documentation at a route like /api-docs. When a user visits this route, they see a web page generated from your API spec. They can explore endpoints and try API calls directly from the docs. The API responds as defined, and the results show in the docs. This flow helps keep your API easy to understand and test.

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