Simple API JSON + Swagger Boilerplate

A minimal Node.js + Express REST API boilerplate that reads from a local JSON file and includes Swagger UI documentation generated with swagger-autogen and served with swagger-ui-express.

Features

• Minimal Node Express REST API
• Reads from a simple .json file (no database required)
• Integrated Swagger UI setup using:
  • swagger-autogen
  • swagger-ui-express
• Works with Node.js 18+ and Node.js 22+ (ESM imports)

Tech Stack

• Node.js
• Express 5
• CORS
• Swagger UI Express
• Swagger Autogen

Installation

1. Create a new project from this template

Click the “Use this template” button at the top of the repo or clone it manually:

git clone https://github.com/ypdev19/node-express-basic-api-json-swagger-boilerplate.git
cd node-express-basic-api-json-swagger-boilerplate

2. Install dependencies

npm install

3. Generate Swagger documentation:

npm run swagger-autogen

4. Start the server:

npm start

• The server will start at http://localhost:8080
• Swagger UI available at http://localhost:8080/api-docs

Node Import Notes

Depending on your Node.js version, you may need to import swagger-output.json differently:

Node 22+ (with ESM)

You can directly import JSON using the assert syntax:

import swaggerFile from "./swagger-output.json" assert { type: "json" };

For Node < 22

Use createRequire instead:

import { createRequire } from "module";
const require = createRequire(import.meta.url);
const swaggerFile = require("./swagger-output.json");

API Endpoints

Method	Path	Description
GET	/api/articles	Get list of articles from JSON
GET	/api-docs	Swagger UI documentation

Usage Tips

• Extend the project by adding new endpoints under src/routes/.
• The "business" logic is under src/service/.
• Update swagger.js to include new routes.
• Store additional datasets under data/.
• Re-run npm run swagger-autogen each time you modify endpoints.

Notes

• This is a lightweight boilerplate meant for quick REST API prototypes.
• No database is required, it reads directly from local JSON.

Related Article

Checkout the step by step tutorial 👉 Add Swagger UI to Nodejs Express REST API: Simple Setup Guide

🪪 License

MIT License © Yuli Petrilli