express-oas-generator

Module to:

• automatically generate OpenAPI (Swagger) specification for existing ExpressJS 4.x REST API applications;
• provide Swagger UI basing on generated specification.

How to use

• Install module npm i express-oas-generator --save;
• Import it in a script where you initialize ExpressJS application (see server.js for usage example);

const express = require('express');
const expressOasGenerator = require('express-oas-generator');

• Run initialization of module right after instantiating app;

let app = express();
expressOasGenerator.init(app, {}); // to overwrite generated specification's values use second argument.

• Important! In order to get description of all parameters and JSON payloads you have to start using your REST API or run REST API tests against it so module can analyze requests/responses
• Assuming you running your app on port 8000
  • open http://localhost:8000/api-docs to see Swagger UI for your REST API
  • specification file is available http://localhost:8000/api-spec - link is prepended to description field

Second argument of expressOasGenerator.init(app, {}) could be either an object or a function. In case of the object generated spec will be merged with the object. In case of function it will be used to apply changes for generated spec. Example of function usage:

generator.init(app, function(spec) {
    _.set(spec, 'info.title', 'New Title');
    _.set(spec, 'paths[\'/path\'].get.parameters[0].example', 2);
    return spec;
});

To write specification into a file use third and forth (optional) arguments:

expressOasGenerator.init(
  app,
  function(spec) { return spec; },
  'path/to/a/file/filename.json',
  60 * 1000
)

where:

• 'path/to/a/file/filename.json' - path to a file and file name
• 60 * 1000 - write interval in milliseconds (optional parameter, by default interval is equal to 10 seconds)

(Optional) Additions to your package.json

If your service is running not at the root of the server add full base path URL to package.json

{
  "baseUrlPath" : "/tokens"
}

Here is a sample

{
  "name": "cwt-sts-svc",
  "version": "1.1.48",
  "description": "JWT generation service",
  "keywords": [],
  "author": "",
  "main": "lib",
  "baseUrlPath" : "/tokens",
  "bin": {
    "cwt-sts-svc": "bin/server"
  }

Rationale

Goal of the module is to provide developers with Swagger UI in development environments. Module process every request and response therefore it may slow down your app - is not supposed to be used in production environment.

Assuming you have ExpressJS REST API application and you

• don't want to write documentation manually;
• but want to use Swagger ecosystem:
  • keep REST API endpoint documented;
  • provide others with Swagger UI to your REST API;
  • generate client libraries for it with Swagger code generator.

How does it work

1. During initialization module iterates through all routes and methods and initializes OpenAPI (Swagger) specification.
2. After an application start module analyze every request/response and fills specification with schemes and examples.
3. Module replace values of password fields with ******

Limitations

1. All headers with prefix X- treated as a apiKey type headers;
2. Module doesn't recognize enumerations in JSON objects;