Registry / devops / oas3-tools

oas3-tools

JSON →
library2.2.3jsnpmunverified

A middleware library for Express.js that provides Swagger UI and API request validation/routing based on OpenAPI 3.0 specifications. Current version 2.2.3 (as of 2023) is in maintenance mode with infrequent updates. It is a fork of the deprecated apigee-127/swagger-tools, adding OpenAPI 3 support. Key differentiators: integrates Swagger UI, request validation, and routing into one Express middleware. However, the project has limited community support and may have compatibility issues with newer Node.js versions. Alternatives include express-openapi-validator or swagger-ui-express.

devopstesting
npm install oas3-tools
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · OAS3-TOOLS
O
oas3-tools
devopsjavascriptv2.2.3
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.

oas3Tools
✓ const oas3Tools = require('oas3-tools')
✗ import oas3Tools from 'oas3-tools'
CommonJS module; no default ESM export. Use require.
ExpressServerConfig
✓ const { ExpressServerConfig } = require('oas3-tools')
✗ import { ExpressServerConfig } from 'oas3-tools'
Named import via destructuring; CommonJS only.
oas3Tools.serve
✓ const options = { ... }; oas3Tools.serve(options, app, callback)
✗ oas3Tools.server(options, app)
Method is .serve(), not .server().
spec
✓ const spec = require('./path/to/openapi.yaml');
✗ import spec from './path/to/openapi.yaml'
YAML/JSON spec loaded via require for CommonJS.

Initializes an Express app with OpenAPI 3 validation, routing, and Swagger UI using oas3-tools.

const express = require('express'); const oas3Tools = require('oas3-tools'); const path = require('path'); const app = express(); const specPath = path.join(__dirname, 'api', 'openapi.yaml'); const options = { controllers: path.join(__dirname, 'controllers'), loglevel: 'info', strict: true, router: true, validator: true }; oas3Tools.serve(options, app, undefined, function(err) { if (err) { console.error(err); return; } const port = process.env.PORT || 3000; app.listen(port, () => console.log(`Listening on ${port}`)); });
Debug
Known issues
gotchaMiddlewares order matters: body-parser must be used before oas3Tools.serve to parse request bodies.
fix
Ensure body-parser is registered before calling oas3Tools.serve.
affects: all
gotchaThe options object passed to .serve() is mutable; do not reuse across calls.
fix
Create a fresh options object for each .serve() call.
affects: all
gotchaOpenAPI spec must be valid YAML/JSON and follow OpenAPI 3.0; errors are silently ignored.
fix
Validate spec with swagger-cli prior to runtime.
affects: all
deprecatedThe 'loglevel' option is deprecated and may be removed in future versions.
fix
Remove 'loglevel' from options; use console.log directly.
affects: >=2.2.0
Errors
Common errors & fixes
Error: Cannot find module 'body-parser'
body-parser is missing from dependencies.
fix
npm install body-parser
TypeError: oas3Tools.serve is not a function
Incorrect import: using default import instead of require.
fix
Use const oas3Tools = require('oas3-tools')
Cannot read property 'paths' of undefined
OpenAPI spec has incorrect structure or missing 'paths'.
fix
Ensure spec object has 'openapi', 'info', and 'paths' fields.
Error: options.controllers must be a string or array of strings
Controllers path is not correctly specified.
fix
Provide absolute or relative path to controllers directory.
Upgrade
Version history
2.2.3latest on npm
Audit
Dependencies
expressrequiredpeer dependency - middleware plugin for Express
body-parserrequiredparses request bodies for validation
Agent activity
10 hits · last 30 days
node
8
Amazon
1
Resources
githubssh://git@github.com/bug-hunters/oas3-tools ↗
packageoas3-tools ↗
homepagehttps://github.com/bug-hunters/oas3-tools ↗
oas3-tools — npm install oas3-tools · libregistry