Registry / web-framework / node-restify-swagger

node-restify-swagger

JSON →
library0.1.8jsnpmunverified

node-restify-swagger is a utility that generates API documentation in the Swagger 1.2 format for web services built with the Restify framework. Published with its latest version 0.1.8 in 2015, the package is largely unmaintained and relies on the deprecated Swagger 1.2 specification, which has since been superseded by OpenAPI Specification (OAS) 2.0 and 3.x. It integrates with `node-restify-validation` to derive documentation from validation schemas, offering basic endpoint documentation and model definitions. Due to its age, it is not recommended for new projects and is unlikely to be compatible with modern Restify versions (which are currently at 11.x and support Node.js v14.x and v16.x) or contemporary API documentation tools.

web-frameworkserializationdevops
npm install node-restify-swagger
github ↗package ↗
INSTALL
IMPORT
SIG · NODE-RESTIFY-SWAGG
N
node-restify-swagger
web-frameworkjavascriptv0.1.8
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

restifySwagger
✓ const restifySwagger = require('node-restify-swagger');
✗ import restifySwagger from 'node-restify-swagger';
This package exclusively uses CommonJS `require()` syntax. It does not support ES module `import`.
restify
✓ const restify = require('restify');
✗ import restify from 'restify';
While `restify` is a dependency, it is also imported via CommonJS and is crucial for setting up the server.
validationPlugin
✓ const restifyValidation = require('node-restify-validation'); // then use restifyValidation.validationPlugin
✗ import { validationPlugin } from 'node-restify-validation';
The `validationPlugin` is a named export from the `node-restify-validation` package, used for server middleware.

Sets up a basic Restify server with Swagger 1.2 documentation, including a POST route with input validation and model definitions, demonstrating how to configure and generate API specs.

const restify = require('restify'); const restifySwagger = require('node-restify-swagger'); const restifyValidation = require('node-restify-validation'); const server = restify.createServer({ name: 'MyRestifyAPI' }); server.use(restify.queryParser()); server.use(restify.bodyParser({ mapParams: true })); // Ensure bodyParser is enabled for POST/PUT requests server.use(restifyValidation.validationPlugin({ errorsAsArray: false, })); restifySwagger.configure(server, { description: 'Description of my API', title: 'Title of my API', allowMethodInModelNames: true }); server.post({ url: '/animals', swagger: { summary: 'Add animal', docPath: 'zoo' }, validation: { name: { isRequired: true, isAlpha:true, scope: 'body' }, locations: { isRequired: true, type:'array', swaggerType: 'Location', scope: 'body' } }, models: { Location: { id: 'Location', properties: { name: { type: 'string' }, continent: { type: 'string' } } } } }, function (req, res, next) { // Example: process the validated body console.log('Received animal:', req.body); res.send(201, req.body); return next(); }); restifySwagger.loadRestifyRoutes(); server.listen(8001, function () { console.log('%s listening at %s', server.name, server.url); console.log('Swagger 1.2 spec available at: http://localhost:8001/swagger/resources.json'); console.log('Zoo endpoint documentation at: http://localhost:8001/swagger/zoo'); });
Debug
Known issues
breakingThis package generates API documentation using the outdated Swagger 1.2 specification. Modern API tooling and frameworks predominantly use OpenAPI Specification (OAS) 2.0 (formerly Swagger 2.0) or 3.x, rendering generated documentation incompatible with current ecosystems like Swagger UI or Postman.
fix
Migrate to a contemporary Restify-compatible OpenAPI documentation generator like `restify-swagger-jsdoc` (for JSDoc annotations) or `swagger-restify-mw` for Swagger 2.0/OpenAPI 3.x support.
affects: >=0.1.0
deprecatedThe `node-restify-swagger` package is abandoned, with its last publish in 2015. There will be no further updates, bug fixes, or security patches, making it unsuitable for production environments.
fix
Replace this package with actively maintained alternatives. For new projects, consider other frameworks like Express with `swagger-jsdoc` or `NestJS` which have robust OpenAPI integrations.
affects: >=0.1.0
gotchaThis package is CommonJS-only and does not support ES Modules (`import/export` syntax). Attempting to use it in an ESM context will result in runtime errors.
fix
Ensure your project is configured for CommonJS, or use dynamic `import()` if necessary within an ESM project, though full compatibility is not guaranteed. Prefer modern ESM-compatible alternatives.
affects: >=0.1.0
breakingThe package's deep integration with specific, older versions of `restify` and `node-restify-validation` means it is highly likely to be incompatible with newer major versions of Restify (e.g., v8, v9, v10, v11) which introduce breaking changes.
fix
Pin Restify and `node-restify-validation` to very old versions (e.g., `restify@^4.x` if compatible) or, ideally, migrate to modern tooling that supports current Restify versions or other frameworks.
affects: >=0.1.0
gotchaThe `swagger` property on routes in `node-restify-swagger` is tightly coupled with its internal processing. Incorrectly formatting this object or omitting required fields will lead to incomplete or malformed API documentation, often without clear error messages. Always refer to the package's specific schema for this property.
fix
Carefully review the example provided in the README and ensure all `swagger` and `models` properties on your routes conform to the package's expected structure for Swagger 1.2 definitions. Debug generated `resources.json` and specific `docPath` JSON outputs.
affects: >=0.1.0
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
Attempting to use `require()` in an ES module environment (.mjs file or `"type": "module"` in package.json).
fix
This package is CommonJS-only. Either revert your project to CommonJS (`.js` files with `"type": "commonjs"` or no `type` field in `package.json`) or switch to a modern, ESM-compatible Swagger integration package.
TypeError: server.use is not a function
Using a non-Restify server instance, or an extremely outdated Restify version that doesn't expose `use` in the expected way, or an object that is not the server instance itself.
fix
Ensure `server` is correctly initialized via `restify.createServer()` and that you are using a compatible, albeit old, version of the `restify` package. Check `restify` documentation for specific API changes across major versions.
TypeError: restifySwagger.configure is not a function
The `restifySwagger` object is not correctly loaded or is undefined, often due to an incorrect `require()` path or an issue with the module resolution.
fix
Verify the `require('node-restify-swagger')` statement is correct and that the package is installed. Double-check for typos in the import path. If using TypeScript, ensure ambient type declarations are not misleading for a CJS package.
Error: listen EADDRINUSE: address already in use :::8001
Another process is already using the specified port (e.g., 8001) on your system.
fix
Change the `server.listen()` port to an unused one (e.g., 3000, 8080) or terminate the process currently occupying the port.
Upgrade
Version history
0.1.8latest on npm
Audit
Dependencies
restifyrequiredCore web framework for which this package generates Swagger documentation.
node-restify-validationrequiredRequired for defining validation schemas that `node-restify-swagger` uses to generate API documentation.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/z0mt3c/node-restify-swagger ↗
packagehttps://www.npmjs.com/package/node-restify-swagger ↗