OpenAPI Spezifikation: Property `location` ist nicht nullable, wird aber mit `null` zurückgegeben

[FelixDamrau]

Die OpenAPI Spezifikation definiert die Property location im Schema Match als nicht nullable:

 "location": {
   "$ref": "#/components/schemas/Location"
 },

Allerdings liefert die API an dieser Stelle null als Rückgabewert. Dies widerspricht der Spezifikation und kann zu Fehlern bei der Verarbeitung der API-Antwort führen, insbesondere wenn Clients Code basierend auf der Spezifikation generieren oder Validierungen durchführen.

Dieses Problem unterscheidet sich von #72 (Featurerequest nach Locationdaten) und könnte ähnlich zu #89 (Javascript-Fehler beim Speichern von Liga-Metadaten) sein.

Beispielrequest mit response außerhalb der Spezifikation:

GET https://api.openligadb.de/getmatchdata/72220
RESPONSE
{
  "matchID": 72220,
  ### SNIP

  ### Hier ist location `null`, obwohl es das nicht sein sollte.
  "location": null,
  "numberOfViewers": null
}

---

Es gibt keine bekannten signifikanten Workarounds für dieses Problem, außer die Validierung der API-Antwort clientseitig anzupassen oder die OpenAPI Spec eigenständig anzupassen.

---

Vorschlag

Man sollte die Spezifikation so anpassen:

"location": {
  "$ref": "#/components/schemas/Location",
    "nullable": true
},

[FelixDamrau]

Noch ein Nachtrag, warum das nicht nur ein kosmetisches Problem ist:

Die Diskrepanz zwischen der OpenAPI-Spezifikation und der tatsächlichen API-Antwort ist problematisch, da sie bei der Code-Generierung "based on the specification" zu Laufzeitfehlern führen kann. Wenn die Spezifikation angibt, dass eine Property nicht nullable ist, generieren Tools wie NSwag (für C#) Code dafür "guards".

Beispiel (C# mit NSwag)

[Newtonsoft.Json.JsonProperty("location", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
public Location Location { get; set; }

Dieses Required = Newtonsoft.Json.Required.DisallowNull führt zu einem Deserialisierungsfehler, wenn die API null für location liefert.