Neophobe Plebeian Mumpsimus

    swagger-ajv

    4.0.0 • Public • Published

    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

    docs

    pass the schema object as specified by openapi

    validation

    pass an object should contain components, paths and ajvOptions paths and components are the schemas that can be referenced from ajv to use ajvOptions are all the options that can be passed to initialise an ajv instance

    Utils

    swaggerAjv.mergeSchemas the first parameter is a string specifying the path of the folder containing schemas the second parameter specifies the options on how the schemas are read

    1. useDirStructre

    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 = {};
    // custom keywarods
    const ajvKeywords = [{
    			name: 'mustPositive',
    			def: {
    				validate: (schema, data) => {
    					return schema ? data > 0 : true;
    				}
    			}
    		}]
    // We have embedded [ajv-errors](https://github.com/epoberezkin/ajv-errors)
    const ajvErrorsOptions = {};
    
    // export middlewares for your application
    exports.docs = docs(schemas.swagger);
    exports.validation = validation(Object.assign(
    	schemas.ajv,
    	{ ajvOptions,
        ajvKeywords,
        ajvErrorsOptions }
    ));
    
    • 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 = {};
    // custom keywarods
    const ajvKeywords = [{
    			name: 'mustPositive',
    			def: {
    				validate: (schema, data) => {
    					return schema ? data > 0 : true;
    				}
    			}
    		}]
    // We have embedded [ajv-errors](https://github.com/epoberezkin/ajv-errors)
    const ajvErrorsOptions = {};
    
    // export middlewares for your application
    exports.docs = docs(schemas.swagger);
    exports.validation = validation(Object.assign(
    	schemas.ajv,
    	{ ajvOptions,
        ajvKeywords,
        ajvErrorsOptions  }
    ));
    

    Credits

    License

    MIT

    Keywords

    none

    Install

    npm i swagger-ajv

    DownloadsWeekly Downloads

    228

    Version

    4.0.0

    License

    MIT

    Unpacked Size

    67.8 kB

    Total Files

    52

    Last publish

    Collaborators

    • aftership