v2.0.0

⚠️ IMPORTANT! ⚠️

This is a new major version that is NOT compatible with the previous one. The validator is used in a totally different way. So be careful when updating your package.

Main changes

• Changed how the validator is used: now you only need to initialize the validator (init(app, options)) after creating the Express application and it will AUTOMATICALLY validate all the requests and responses (depending on the configuration options when initializing). No need to call the validate method explicitly (before validateAPIInput() and validateAPIOutput() had to be called).

• Added normalizeOptions module to normalize options input parameter and to set default values if any parameter is not set by the user.

• Added openAPISpecification module to generate the OpenAPI specification based on the format of the documentation used by the user to document the endpoints of the API. Supported formats are:

  • yaml if the documentation is stored in a yaml file (see js-yaml).
  • yaml_jsdoc if the documentation is generated using yaml format in inline JSDoc documents tagged with @swagger (see swagger-jsdoc).
  • jsdoc if the documentation is generated using pure JSDoc format (see express-swagger-generator).

• Added customErrorHandler that catches requests validation errors and sends a custom error.

• Added validationEndpoint module to add an optional endpoint to be able to do explicit requests and responses validation (e.g. for e2e tests of the API).

• Removed dependency from swagger-model-validator.

Minor changes

• huskyrc has been removed. Now it's inside package.json.
• Improved methods documentation.
• Added debug information (prefix: swagger-endpoint-validator).
• Added lib/constants.js file to store constants used across the library.

3rd party libraries used

• express-openapi-validator: this is the core library used to automatically validate API requests and responses using an OpenAPI 3 specification.
• swagger2openapi: used to convert from OpenAPI 2.0 to OpenAPI 3.0.x
• js-yaml: parses string as single YAML document and returns a JavaScript object. Used when the user uses a yaml format to write the API documentation.
• express-swagger-generator: allows to integrate OpenAPI using JSDoc comments and generates the OpenAPI specification (v2 format). Used when the user uses a yaml_jsdoc format file to write the API documentation.
• swagger-jsdoc: allows to integrate Swagger using JSDoc comments in the code by just adding @swagger on top of the DocBlock and generates the OpenAPI specification (v3 format). Used when the user uses a jsdoc format to write the API documentation.
• openapi-enforcer: this library is used to be able to do independent validation of values against OAS schemas.
• supertest: this is used in development to do e2e testing of the API.

Work in progress

There is still some work to be done. We are releasing the first version of this new validator so we can start using it. But these issues will be added to the backlog to work on them:

• Update documentation (README).
• Add unitary tests.
• Add optional endpoint validation tests.
• Support for allOf and other tags added in the OpenAPI v3 spec.
• Optional publication of the generated API doc (swagger-ui-express)
• Investigate validator-badge
• Add issue in express-swagger-generator because it doesn't type: object to the schemas and we have to do it manually.