Restify Swagger 1.2 Integrator

Common errors

• ReferenceError: require is not defined in ES module scope

  cause 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

  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.
  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

  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.
  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

  cause 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.

Warnings

• breaking 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.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-restify-swagger npm
• yarn add node-restify-swagger yarn
• pnpm add node-restify-swagger pnpm

Imports

• restifySwagger
  wrong:

  import restifySwagger from 'node-restify-swagger';

  correct:

  const restifySwagger = require('node-restify-swagger');

  This package exclusively uses CommonJS `require()` syntax. It does not support ES module `import`.
• restify
  wrong:

  import restify from 'restify';

  correct:

  const restify = require('restify');

  While `restify` is a dependency, it is also imported via CommonJS and is crucial for setting up the server.
• validationPlugin
  wrong:

  import { validationPlugin } from 'node-restify-validation';

  correct:

  const restifyValidation = require('node-restify-validation');
  // then use restifyValidation.validationPlugin

  The `validationPlugin` is a named export from the `node-restify-validation` package, used for server middleware.

Quickstart

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');
});