open-api

Use openapi-default-setter to automatically populate missing header and query request properties with default values defined in your OpenAPI (Swagger 2.0) parameter lists.

Key Behaviors:

• Supported Locations: It sets defaults for header and query parameters.
• Unsupported Locations: Path parameters are not supported (it is assumed path parameters will always have a value).
• No Coercion or Validation: This package does not perform type coercion or request validation. For those tasks, use openapi-request-coercer and openapi-request-validator respectively.

import OpenAPIDefaultSetter from 'openapi-default-setter';

const defaultSetter = new OpenAPIDefaultSetter({
  parameters: [
    {
      in: 'query',
      type: 'integer',
      name: 'foo',
      default: 5
    }
  ]
});

const request = { query: {} };

defaultSetter.handle(request);

console.log(request.query.foo); //=> 5

If your route files export a function instead of an object, you can use args.dependencies to inject services or data providers directly into the function arguments. The keys in the dependencies object must match the parameter names in your exported function.

Implementation Pattern

1. Define dependencies in the initialize call.
2. Export a function from your route file that accepts those dependencies as arguments.

// app.js
var mockDataProvider = require("custom-mock-data-provider");
var geoService = require("awesome-geo-service")({url: "http.example.com/geoservice"});

initialize({
    apiDoc: require('./api-doc.js'),
    app: app,
    paths: [path.resolve(__dirname, 'api-paths')],
    dependencies: {
        dataprovider: mockDataProvider(),
        geoservice: geoService
    }
});

// api-paths/users.js
module.exports = function(geoservice, dataprovider) {
    var doc = {
        GET: function (req, res, next) {
            res.json({
                user: dataprovider.getUser(req.params.userid), 
                location: geoservice.getUserLocation(req.params.userid)
            });
        }
    };
    doc.GET.apiDoc = { /* ... */ };
    return doc;
};

Use openapi-request-validator to validate incoming request properties (headers, body, params, query) against an OpenAPI specification.

Key Behaviors:

• It leverages jsonschema for validation.
• It supports $ref in body schemas (e.g., #/definitions/SomeType).
• Note: It does not perform type coercion (use openapi-request-coercer) or supply default values (use openapi-default-setter).
• Note: It does not validate parameter input directly; it converts parameter input to JSON Schema using openapi-jsonschema-parameters.

To use it, instantiate OpenAPIRequestValidator with your specification details and call validateRequest(request).

var OpenAPIRequestValidator = require('openapi-request-validator').default;

var requestValidator = new OpenAPIRequestValidator({
  parameters: [
    {
      in: 'query',
      type: 'string',
      name: 'foo',
      required: true
    }
  ],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          properties: {
            name: { type: 'string' }
          }
        }
      }
    }
  },
  schemas: null,
  errorTransformer: null,
  customFormats: {
    foo: function(input) {
      return input === 'foo';
    }
  }
});

var request = {
  headers: { 'content-type': 'application/json' },
  body: {},
  params: {},
  query: {foo: 'wow'}
};

var errors = requestValidator.validateRequest(request);
if (errors) {
  console.log(errors);
}

To support security schemes defined in your apiDoc (like apiKey or basic auth), provide a mapping of scheme names to handler functions in args.securityHandlers. Each handler is responsible for validating the request and can return a Promise.

Configuration

1. Define securityDefinitions in your apiDoc.
2. Map those names to handlers in initialize.
3. Use the security property in your operation apiDoc to apply them.

// 1. apiDoc definition
var apiDoc = {
  swagger: 2.0,
  securityDefinitions: {
    keyScheme: {
      type: 'apiKey',
      name: 'api_key',
      in: 'header'
    }
  }
};

// 2. Initialization
initialize({
  apiDoc: apiDoc,
  app: app,
  securityHandlers: {
    keyScheme: function(req, scopes, definition) {
      // Validate key and return Promise.resolve(true) or reject
      return Promise.resolve(true);
    }
  }
});

// 3. Operation usage
function myHandler(req, res) { /* ... */ }
myHandler.apiDoc = {
  security: [{ keyScheme: [] }]
};

To use express-openapi, follow these four steps to set up a documented API with automatic path generation and dependency injection:

1. Create an apiDoc: Define your main OpenAPI specification (Swagger 2.0 or OpenAPI 3.0) in a JavaScript object or a YAML file. You can leave the paths object empty, as express-openapi will populate it based on your path handlers.
2. Create path handlers: Place your path handlers in a directory (e.g., ./api-v1/paths/). Each file should export an object where keys are HTTP methods (e.g., GET, POST). To enable OpenAPI features like validation for a specific method, attach an apiDoc property to that method function.
3. Create services: Define your business logic in service files. These can be injected into your path handlers.
4. Initialize the app: Use the initialize function, passing your Express app, the apiDoc, the directory containing your paths, and a dependencies object to map service names to their implementations.

express-openapi automatically adds a Swagger UI route at apiDoc.basePath + args.docsPath.

// 1. api-doc.js
const apiDoc = {
  swagger: '2.0',
  basePath: '/v1',
  info: { title: 'API', version: '1.0.0' },
  definitions: { ... },
  paths: {}
};

// 2. paths/worlds.js
export default function(worldsService) {
  let operations = { GET };
  function GET(req, res, next) {
    res.status(200).json(worldsService.getWorlds(req.query.worldName));
  }
  GET.apiDoc = {
    summary: 'Returns worlds by name.',
    parameters: [{ in: 'query', name: 'worldName', required: true, type: 'string' }],
    responses: { 200: { description: 'Success', schema: { type: 'array', items: { $ref: '#/definitions/World' } } } }
  };
  return operations;
}

// 3. services/worldsService.js
const worldsService = { getWorlds: (name) => [...] };

// 4. app.js
import { initialize } from 'express-openapi';
const app = express();
initialize({
  app,
  apiDoc: v1ApiDoc,
  dependencies: { worldsService: v1WorldsService },
  paths: './api-v1/paths'
});
app.listen(3000);