swagger-ajv ·

The middleware for validating and documenting express and koa applications.

• Validation is done using AJV.
• Documentation is done using Swagger.

Compatible with node >= 4

Specification

NOTE: The middleware must be applied to the router not the application when using koa.

The documentation should be written using OpenAPI 3.0 specification with the differences listed below. The differences with JSON schema can be noted here. When writing schema for your application please note that the keywords must be used in a way that can be supported by both Swagger and AJV.

• type can be an array with "null" as the second element when "nullable": true property needs to be used as mentioned in the OpenAPI.

"type": "string"

"type": ["string", "null"],
"nullable": true

Reference

swaggerAjv is used to refer to the library which would be required as require('swagger-ajv')

Middlewares

swaggerAjv.middlewares.express

• docs
• validation

swaggerAjv.middlewares.koa

• docs
• validation

Utils

swaggerAjv.mergeSchemas

Test

yarn test

Building

yarn build

Examples

Define schemas for your application

Componenet.json

schema for new component should be defined under components.schemas if written in separate files

{
  "components": {
    "schemas": {
      "Component": {
        "type": "object"
      }
    }
  }
}

swagger.json

keys other than components and paths defined in a separate file

{
  "openapi": "3.0.0"
}

path.json

schema for a path should be defined as under paths key if written in separate files

{
  "paths": {
    "/post": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": ["string", "null"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Component"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Write middleware in your favourite framework

• Express examples/express.js

'use strict';

const path = require('path');

const swaggerAjv = require('../src');

const {docs, validation} = swaggerAjv.middlewares.express;

const {mergeSchemas} = swaggerAjv.utils;

// load schema definitions
const schemas = mergeSchemas(
	path.resolve(__dirname, 'schemas')
);

// define ajvOptions
const ajvOptions = {};

// export middlewares for your application
exports.docs = docs(schemas.swagger);
exports.validation = validation(Object.assign({
	schemas.ajv,
	ajvOptions
}));

• Koa examples/koa.js

'use strict';

const path = require('path');

const swaggerAjv = require('../src');

const {docs, validation} = swaggerAjv.middlewares.koa;

const {mergeSchemas} = swaggerAjv.utils;

// load schema definitions
const schemas = mergeSchemas(
	path.resolve(__dirname, 'schemas')
);

// define ajvOptions
const ajvOptions = {};

// export middlewares for your application
exports.docs = docs(schemas.swagger);
exports.validation = validation(Object.assign({
	schemas.ajv,
	ajvOptions
}));

Credits

• AJV
• Swagger

License

MIT