OpenAPI JSON Validator

Veelvoorkomende JSON-fouten die een controle laten mislukken

JSON is strikter dan YAML, dus de meeste fouten in een met de hand bewerkt bestand komen door de syntaxis en niet door het ontwerp van de API. De gebruikelijke oorzaken zijn een komma na de laatste eigenschap, enkele in plaats van dubbele aanhalingstekens, een commentaar (JSON staat dat niet toe) of een ontbrekende sluitende accolade na een lang paths-object. Een kapot bestand eindigt meestal met de melding “Kan niet als JSON of YAML worden gelezen”, of met fouten over ontbrekende velden omdat er niets bruikbaars is gelezen.

Als u alleen een parseerfout ziet, zoek dan eerst de syntaxisfout. De structuurcontroles draaien zodra het document als object kan worden gelezen.

Een uitgewerkt voorbeeld

Neem dit kleine document:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Het wordt gelezen, en het veld openapi en het object paths zijn aanwezig. Het rapport zou toch het volgende tonen:

Omdat er één fout is, wordt het document niet als geldig gemeld. Voeg "version": "1.0.0" toe aan info en hernoem de sleutel naar /orders. Een tweede run haalt beide bevindingen weg.

Wat een geslaagde controle wel en niet betekent

Een schoon rapport betekent dat het skelet klopt. Het volgt geen $ref-verwijzingen, controleert geen schema’s en bevestigt niet dat elke bewerking responses heeft. Zie het als een snelle poort voordat u het bestand vastlegt, en draai daarna een volledige linter voor de diepere regels.

Een praktische werkwijze voor JSON-specificaties

Bewaar de specificatie in versiebeheer en plak ze hier vóór elke commit die paths wijzigt. Omdat de controle snel is, werkt hij als gezondheidscheck na het samenvoegen van wijzigingen van meerdere personen, wanneer dubbele sleutels of een verkeerd geplaatste accolade het waarschijnlijkst zijn. Als uw JSON door een buildscript wordt gegenereerd, plak dan de gegenereerde uitvoer en niet de sjabloon, zodat u test wat lezers werkelijk krijgen. Als het rapport schoon is, deel het bestand of geef het aan een documentatiegenerator met meer vertrouwen dat de structuur op het hoogste niveau deugt.