node-api-swagger-kit

Zero-config Swagger UI and OpenAPI 3 generation for Express.js. Add one middleware and visit /api-docs, similar to the default Swagger experience in ASP.NET Core.

Features

• Scans Express routes, including nested routers.
• Generates an OpenAPI 3.0 JSON document.
• Serves Swagger UI at /api-docs.
• Supports browser testing with Swagger UI "Try it out".
• Adds JWT Bearer authentication support to the Swagger UI Authorize dialog.
• Detects GET, POST, PUT, DELETE, PATCH, OPTIONS, and HEAD routes.
• Converts Express path parameters such as /users/:id to OpenAPI paths such as /users/{id}.
• Infers query parameters from common req.query usage.
• Adds JSON request bodies when handlers read req.body.

Installation

npm install node-api-swagger-kit

Peer application dependencies:

npm install express

Usage

import express from 'express';
import apiDocs from 'node-api-swagger-kit';

const app = express();

app.use(express.json());

app.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id });
});

app.post('/users', (req, res) => {
  res.status(201).json(req.body);
});

app.use(apiDocs({
  title: 'My API',
  version: '1.0.0'
}));

app.listen(3000);

Visit:

• Swagger UI: http://localhost:3000/api-docs
• OpenAPI JSON: http://localhost:3000/api-docs.json

Options

app.use(apiDocs({
  title: 'My API',
  version: '1.0.0',
  description: 'Generated API documentation.',
  servers: [{ url: '/' }],
  docsPath: '/api-docs',
  jsonPath: '/api-docs.json',
  cache: true,
  swaggerOptions: {
    persistAuthorization: true
  }
}));

JWT Bearer Tokens

The generated OpenAPI document includes this security scheme:

components: {
  securitySchemes: {
    bearerAuth: {
      type: 'http',
      scheme: 'bearer',
      bearerFormat: 'JWT'
    }
  }
}

Open Swagger UI, click Authorize, and paste your JWT. Swagger UI will send it as:

Authorization: Bearer <token>

Demo

npm install
npm run example

Then open http://localhost:3000/api-docs.

Notes

Express does not expose rich route metadata by default. This package safely inspects the internal Express router stack and uses lightweight heuristics for query parameters and request bodies. For production APIs with strict schemas, you can extend the generated spec after scanning or add explicit schemas in a future wrapper.