{"id":14756,"library":"node-restify-swagger","title":"Restify Swagger 1.2 Integrator","description":"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.","status":"abandoned","version":"0.1.8","language":"javascript","source_language":"en","source_url":"git://github.com/z0mt3c/node-restify-swagger","tags":["javascript","rest","api","restify","validation"],"install":[{"cmd":"npm install node-restify-swagger","lang":"bash","label":"npm"},{"cmd":"yarn add node-restify-swagger","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-restify-swagger","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core web framework for which this package generates Swagger documentation.","package":"restify"},{"reason":"Required for defining validation schemas that `node-restify-swagger` uses to generate API documentation.","package":"node-restify-validation"}],"imports":[{"note":"This package exclusively uses CommonJS `require()` syntax. It does not support ES module `import`.","wrong":"import restifySwagger from 'node-restify-swagger';","symbol":"restifySwagger","correct":"const restifySwagger = require('node-restify-swagger');"},{"note":"While `restify` is a dependency, it is also imported via CommonJS and is crucial for setting up the server.","wrong":"import restify from 'restify';","symbol":"restify","correct":"const restify = require('restify');"},{"note":"The `validationPlugin` is a named export from the `node-restify-validation` package, used for server middleware.","wrong":"import { validationPlugin } from 'node-restify-validation';","symbol":"validationPlugin","correct":"const restifyValidation = require('node-restify-validation');\n// then use restifyValidation.validationPlugin"}],"quickstart":{"code":"const restify = require('restify');\nconst restifySwagger = require('node-restify-swagger');\nconst restifyValidation = require('node-restify-validation');\n\nconst server = restify.createServer({ name: 'MyRestifyAPI' });\nserver.use(restify.queryParser());\nserver.use(restify.bodyParser({ mapParams: true })); // Ensure bodyParser is enabled for POST/PUT requests\nserver.use(restifyValidation.validationPlugin({\n    errorsAsArray: false,\n}));\n\nrestifySwagger.configure(server, {\n    description: 'Description of my API',\n    title: 'Title of my API',\n    allowMethodInModelNames: true\n});\n\nserver.post({\n    url: '/animals',\n    swagger: {\n        summary: 'Add animal',\n        docPath: 'zoo'\n    },\n    validation: {\n        name: { isRequired: true, isAlpha:true, scope: 'body' },\n        locations: { isRequired: true, type:'array', swaggerType: 'Location', scope: 'body' }\n    },\n    models: {\n        Location: {\n            id: 'Location',\n            properties: {\n                name: { type: 'string' },\n                continent: { type: 'string' }\n            }\n        }\n    }\n}, function (req, res, next) {\n    // Example: process the validated body\n    console.log('Received animal:', req.body);\n    res.send(201, req.body);\n    return next();\n});\n\nrestifySwagger.loadRestifyRoutes();\n\nserver.listen(8001, function () {\n    console.log('%s listening at %s', server.name, server.url);\n    console.log('Swagger 1.2 spec available at: http://localhost:8001/swagger/resources.json');\n    console.log('Zoo endpoint documentation at: http://localhost:8001/swagger/zoo');\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=0.1.0"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` in an ES module environment (.mjs file or `\"type\": \"module\"` in package.json).","error":"ReferenceError: require is not defined in ES module scope"},{"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.","cause":"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.","error":"TypeError: server.use is not a function"},{"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.","cause":"The `restifySwagger` object is not correctly loaded or is undefined, often due to an incorrect `require()` path or an issue with the module resolution.","error":"TypeError: restifySwagger.configure is not a function"},{"fix":"Change the `server.listen()` port to an unused one (e.g., 3000, 8080) or terminate the process currently occupying the port.","cause":"Another process is already using the specified port (e.g., 8001) on your system.","error":"Error: listen EADDRINUSE: address already in use :::8001"}],"ecosystem":"npm"}