An OpenApi validator for ExpressJS that automatically validates API requests using an OpenAPI 3.x specification,

Clone this repo:
  1. 23f930e Update README.md by Carmine DiMascio · 3 years, 6 months ago master
  2. 5681e1f Update README.md by Carmine DiMascio · 3 years, 6 months ago v0.53.3
  3. b7d2aec Update README.md by Carmine DiMascio · 3 years, 6 months ago
  4. c1d750b update readme by Carmine DiMascio · 3 years, 6 months ago
  5. cf20341 increment version by Carmine DiMascio · 3 years, 6 months ago

express-openapi-validator

Coverage Status

An OpenApi validator for ExpressJS that automatically validates API requests using an OpenAPI 3 specification.

express-openapi-validator is unopinionated and does not impose any coding convention or project structure. Simply, install the validator onto your express app, point it to your OpenAPI 3 specification, then define and implement routes the way you prefer. See an example.

Install

npm i express-openapi-validator

Usage

Install the openapi validator

new OpenApiValidator({
  apiSpecPath: './openapi.yaml',
}).install(app);

Then, register an error handler to customize errors

app.use((err, req, res, next) => {
  // format error
  res.status(err.status).json({
    errors: err.errors,
  });
});

Example Express API Server

Try the complete example below: (it includes file upload as well!)

var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var bodyParser = require('body-parser');
var logger = require('morgan');
var http = require('http');
var app = express();

// 1. Import the express-openapi-validator library
var OpenApiValidator = require('express-openapi-validator').OpenApiValidator;

app.use(bodyParser.json());
app.use(logger('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));

// 2. (optionally) Serve the OpenAPI spec
const spec = path.join(__dirname, 'openapi.yaml');
app.use('/spec', express.static(spec));

// 3. Install the OpenApiValidator onto your express app
new OpenApiValidator({
  apiSpecPath: './openapi.yaml',
}).install(app);

// 4. Define routes using Express
app.get('/v1/pets', function(req, res, next) {
  res.json([{ id: 1, name: 'max' }, { id: 2, name: 'mini' }]);
});

app.post('/v1/pets', function(req, res, next) {
  res.json({ name: 'sparky' });
});

app.get('/v1/pets/:id', function(req, res, next) {
  res.json({ id: req.params.id, name: 'sparky' });
});

// 4. Define route(s) to upload file(s)
app.post('/v1/pets/:id/photos', function(req, res, next) {
  // files are found in req.files
  // non-file multipart params can be found as such: req.body['my-param']

  res.json({
    files_metadata: req.files.map(f => ({
      originalname: f.originalname,
      encoding: f.encoding,
      mimetype: f.mimetype,
      // Buffer of file conents
      buffer: f.buffer,
    })),
  });
});

// 5. Create an Express error handler
app.use((err, req, res, next) => {
  // 6. Customize errors
  res.status(err.status).json({
    errors: err.errors,
  });
});

Example Express API Server (clone it)

A fully working example lives here

Example validation responses

Validate a query parameter with a value constraint

/pets/:id should be of type integer, express-openapi-validator returns:

curl http://localhost:3000/v1/pets/as |jq
{
  "errors": [
    {
      "path": "id",
      "errorCode": "type.openapi.validation",
      "message": "should be integer",
      "location": "path"
    }
  ]
}

Validate a query parameter with a range constraint

/pets?limit=? should be of type integer with a value greater than 5. It should also require an additional query paramter, test, express-openapi-validator returns:

curl http://localhost:3000/v1/pets?limit=1 |jq
{
  "errors": [
    {
      "path": "limit",
      "errorCode": "minimum.openapi.validation",
      "message": "should be >= 5",
      "location": "query"
    },
    {
      "path": "test",
      "errorCode": "required.openapi.validation",
      "message": "should have required property 'test'",
      "location": "query"
    }
  ]
}

Validate the query parameter's value type

POST /pets is defined to only accept media type application/json, express-openapi-validator returns:

curl --request POST \
  --url http://localhost:3000/v1/pets \
  --header 'content-type: application/xml' \
  --data '{
        "name": "test"
}' |jq
{
  "errors": [
    {
      "message": "Unsupported Content-Type application/xml"
    }
  ]
}

Validate a POST body to ensure required parameters are present

POST /pets request body is required to contain the name properly, express-openapi-validator returns:

λ  my-test curl --request POST \
  --url http://localhost:3000/v1/pets \
  --header 'content-type: application/json' \
  --data '{
}'|jq
  "errors": [
    {
      "path": "name",
      "errorCode": "required.openapi.validation",
      "message": "should have required property 'name'",
      "location": "body"
    }
  ]
}

Validate a POST multipart/form-data request

curl -XPOST http://localhost:3000/v1/pets/10/photos -F filez=@app.js | jq
{
  "errors": [
    {
      "path": "file",
      "errorCode": "required.openapi.validation",
      "message": "should have required property 'file'",
      "location": "body"
    }
  ]
}

...and much more. Try it out!

License

MIT