Registry / devops / express-oas-generator

express-oas-generator

library1.0.48jsnpmunverified

Automatically generates OpenAPI (Swagger) specifications for Express.js 4.x REST APIs from runtime request/response analysis. Version 1.0.48 provides both Swagger UI and spec endpoints, supports OpenAPI 2 and 3 (default v2), and allows customization via merge objects or callback functions. Releases follow a maintenance cadence with limited recent activity. Key differentiators: no manual annotation required, works with existing routes, supports Mongoose model integration for definitions (requires mongoose, mongoose-to-swagger, bson as peer deps). Full TypeScript definitions included. Note: spec generation is reactive—must exercise endpoints before specs appear.

devops

npm install express-oas-generator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPRESS-OAS-GENERA

express-oas-generator

devopsjavascriptv1.0.48

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import expressOasGenerator from 'express-oas-generator'

ESM default import. CommonJS: const expressOasGenerator = require('express-oas-generator').

init

✓ expressOasGenerator.init(app, options)

✗ init(app)

Second argument is required but can be empty object or function.

SPEC_OUTPUT_FILE_BEHAVIOR

✓ import { SPEC_OUTPUT_FILE_BEHAVIOR } from 'express-oas-generator'

Named export for controlling spec file behavior (e.g., RECREATE).

Initializes express-oas-generator with Express app, then defines a simple route. Open Swagger UI at /api-docs after hitting endpoints.

import express from 'express'; import expressOasGenerator from 'express-oas-generator'; const app = express(); const port = 8000; // must be called before any route definitions expressOasGenerator.init(app, {}); app.get('/hello', (req, res) => { res.json({ message: 'Hello World' }); }); app.listen(port, () => { console.log(`Server running on port ${port}`); console.log(`Swagger UI: http://localhost:${port}/api-docs`); });

Debug

Known issues

gotchaSpecification is empty until endpoints are actually called (runtime analysis).

fix

Exercise your API (e.g., with tests or curl) to populate the spec.

affects: >=0.0.0

deprecatedThe default OpenAPI version is v2 (Swagger 2.0), not v3.

fix

If you need OpenAPI 3, access /api-docs/v3 or /api-spec/v3 explicitly.

affects: >=1.0.0

gotchaMongoose model definitions require all three peer dependencies (mongoose, mongoose-to-swagger, bson) to be installed; missing any causes silent failure.

fix

Ensure all three are in package.json dependencies.

affects: >=1.0.0

breakingSecond argument to init() is required (object or function); passing nothing will cause a runtime error.

fix

Provide at least an empty object: init(app, {}).

affects: >=1.0.0

gotchaModule mutates the Express app (adds middleware) immediately on init(); order matters if you add routes after init, they may not be captured.

fix

Call init() after defining all routes, or ensure routes are registered before first request.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'paths')

Spec not yet generated because no endpoints have been called.

fix

Make at least one request to your API before accessing /api-spec.

TypeError: expressOasGenerator.init is not a function

Using named import incorrectly; default import or require needed.

fix

Use default import: import expressOasGenerator from 'express-oas-generator' or const expressOasGenerator = require('express-oas-generator').

Error: Mongoose model "User" not found

Passing model names to init() but mongoose/models not yet compiled.

fix

Initialize mongoose models before calling init(), or use mongoose.modelNames() after model registration.

Spec file not written

Third argument (file path) missing or write interval not yet elapsed.

fix

Ensure file path is provided as third argument to init() and wait for write interval (default 10s).

Upgrade

Version history

1.0.48latest on npm

Audit

Dependencies

bsonoptionalpeer dependency required for Mongoose model definitions

mongooseoptionalpeer dependency required for Mongoose model definitions

mongoose-to-swaggeroptionalpeer dependency required for Mongoose model definitions

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/mpashkovskiy/express-oas-generator ↗

packageexpress-oas-generator ↗

homepagehttps://github.com/mpashkovskiy/express-oas-generator#readme ↗