Swagger object validator

Validate models against a swagger spec and receive in-depth error traces
  1. Swagger V2.0
  2. In-depth validation error stacks
  3. Extremely Flexible API
  4. Constraint validation

What?

Validate an Object against a given swagger (V2.0) API definition.

A swagger definition specifies an API with requests and data models, and there are a lot of compilers to create server and client skeletons. There are some tools that validate the requests that were sent to the server, but surprisingly there is a huge lack of (good) validators for response bodies.

Why this and not some other tool?

The API is awesome, it gives you easy and full control over what’s happening:

  • Every error has a detailed stack trace so you can find where and what is wrong easily
  • Stack traces are in a format that allows computer programs to understand what’s wrong without parsing strings
  • You can add your own rules or ignore certain errors
  • Other tools do not like splitted specifications (via $ref)
  • Most other tools do not implement very special constraints (like regex, int32/int64, minItems…)

Validation

The following swagger specifications are validated:

  • All the basic stuff like Numbers, Strings, Enums, Arrays, Objects
  • Required properties
  • Int32/Int64, Float/Double, Booleans
  • Dates and Date-Times
  • Maps (additionalProperties)
  • Inheritance (allOf)
  • Polymorphism (discriminator)
  • Custom polymorphism that uses enums
  • All kinds of references ($ref)

Flexible API

  • Load your swagger spec from a JSON/yaml file, the interwebs or load it yourself and do your stuff first
  • Validate your object either by name or by a specification object
  • Get useful stack traces of all the validation errors that occured
  • Stack traces are readable by both programs and humans
  • Need to add custom validation rules or ignore certain errors? No problem!
  • TypeScript support

Error Traces

One of the core features are detailed error traces. One example output:

Type mismatch:
	 - At Pets[3]/Pet<Dog>/age
	 - Should be: "number"
	 - Is: "string"

This translates to: In the pet array, the fourth pet (count starts at 0) may be any pet (polymorphism), but this specific pet is a dog, and its age is a string instead of a number.

This is the human readable error trace. There is another computer readable stack trace, so your application can react accordingly without string parsing.

Project Setup

  • TypeScript
  • Node.js
  • npm scripts
  • Completely test driven by chai and mocha

Usage

  • Intended to be back end only
  • Because of community CRs now usable in Frontend, too
  • Intended to be extremely simple
  • Fantastic error stacks allow computers and humans to understand errors

Unique features

  • Again: These gorgeous error stacks
  • Both swagger and custom polymorphism is detected and validated
  • To increase security, HTTP and HTTPS (both allowed by swagger) requests may be deactivated
  • Add your own validation rules or overrule certain errors

More Information

For more information, downloads and usage please visit npm or github.