Von Sets zu Arrays im OpenAPI Generator

Das OpenAPI Generator Projekt ist enorm hilfreich, wenn man auf Schnittstellen mit OpenAPI Dokumentation zugreifen möchte. Hiermit lassen sich für unterschiedliche Programmiersprachen und Frameworks passende programmatisch ansteuerbare Schnittstellen automatisch generieren und anpassen (siehe auch OpenAPI – Ein eigenes Model).

Bei der Verwendung des typescript-angular Generator ist uns vor Kurzem nun aber ein schon länger bestehendes Problem wieder über den Weg gelaufen. Im Kontext einer Webanwendung mit Spring Boot Backend und Angular Frontend verwenden wir den Generator um die TypeScript Schnittstelle auf Basis der implementieren REST-Schnittstelle des Backends bereitzustellen. Das Problem zeigt sich nun z.B. bei der Verwendung von Sets in unseren Java Typen, die über die Schnittstelle bereitgestellt werden. Die OpenAPI Dokumentation weist diese dann korrekt mit dem Flag uniqueItems aus.

"persons": {
    "uniqueItems": true,
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/Person"
    }
}

Der Generator erzeugt aus dem Schema auch Datentypen mit Attributen vom Typ Set.

persons?: Set<Person>;

Bei der Deserialisierung der Daten an der generierten Schnittstelle wird aber offenbar nicht weiter beachtet welchen Typ das Attribut im Schema hat und die JSON-Daten einfach übernommen. JSON kennt leider keine Sets und so befindet sich an der entsprechenden Stelle zur Laufzeit ein Array.

Das stellt uns nun vor die Herausforderung, dass ein Zugriff auf Array Methoden vom TypeScript Compiler unterbunden wird (außer wir verzichten auf die Typensicherheit) und die Set Methoden zur Laufzeit undefiniert sind.

Immerhin können wir auch hier den Generator mit einem kleinen Workaround umkonfigurieren, damit zumindest der Attributtyp zur Laufzeit mit dem beim Build übereinstimmt. Mithilfe von type-mappings können wir in den generierten Models die Sets zentral durch Arrays ersetzen. Das geht im Falle des openapi-generator-cli Tools einfach per Command-Line-Option --type-mappings=set=Array oder über die JSON-Konfiguration.

{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  [...]
  "generator-cli": {
    [...]
    "generators": {
      "typescript-angular": {
        [...]
        "typeMappings": {
          "set": "Array"
        }
      }
    }
  }
}

Das GitHub Issue zum geschilderten Problem gibt es hier.