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.