Swagger object validator

Was?

Validiert ein Objekt gegen eine gegebene Swagger (V2.0) API-Definition.

Eine Swagger-Definition spezifiziert eine API mit Anfrage- und Antwort-Aufbauten, und es gibt einige Compiler um Server und Clients zu generieren. Es gibt ein paar Tools, die die Requests zum Server validieren, aber überraschenderweise gibt es keine (guten) Validatoren um die Antworten zu prüfen.

Warum dieses und nicht ein anderes Tool?

Die API ist fantastisch. Sie gibt einem einfachen und vollen Zugriff über was passiert:

• Jeder Fehler besitzt einen detaillierten Fehlerbericht, sodass man einfach herausfinden kann, was falsch ist
• Fehlerberichte sind in einem Format, das Computer einfach verstehen, ohne dass man Strings parsen muss
• Man kann eigene Regeln einbauen oder bestimmte Fehler ignorieren
• Andere Tools unterstützen keine aufgeteilten Spezifikationen (über $ref)
• Die meisten anderen Tools unterstützen keine Restriktionen (constraints) (wie regex, int32/int64, minItems…)

Validierung

Die folgenden Swagger-Spezifikationen werden berücksichtigt:

• Aller Grund-Kram wie Zahlen, Strings, Enums, Arrays, Objekte
• Pflichtfelder
• Int32/Int64, Float/Double, Booleans
• Dates und Date-Times
• Maps (additionalProperties)
• Vererbung (allOf)
• Polymorphismus (discriminator)
• Komplexer Polymorphism, das Enums benutzt
• Alle Arten von Referenzen ($ref)

Flexible API

• Die Swagger-Spec lässt sich aus einer JSON/yaml file oder dem Internetz laden. Oder man lädt sie auf eigene Faust und übergibt sie danach.
• Validierung eines Objektes entweder mit Hilfe des Namens oder mit dem Spezifikations-Objekt
• Super-hilfreiche Fehlerberichte aller Validations-Fehlern
• Fehlerberichte sind sowohl maschinell als auch von Menschen lesbar
• Eigene Validierungs-Regeln oder Ignorieren von bestimmten Fehlern gewünscht? Kein Problem!
• TypeScript-Unterstützung

Error-Traces

Einer der Haupt-Features sind die detaillierten Fehler-Beschreibungen. Eine Beispiel-Ausgabe:

Type mismatch:
	 - At Tiere[3]/Tier<Hund>/alter
	 - Should be: "number"
	 - Is: "string"

Dies liest sich so: Im Tiere-Array kann das vierte Tier (Zählen beginnt bei 0) irgend ein Tier sein (Polymorphismus), aber dieses spezielle Tier ist ein Hund, und sein Alter ist ein String statt einer Zahl.

Dies ist ein menschenlesbarer Fehler-Stack. Es gibt einen extra maschinell lesbaren Stack, damit Applikationen ohne String-Parsing richtig darauf reagieren können.