OpenAPI ist eine fantastische Möglichkeit, die eigenen Schnittstellen technisch zu beschreiben und Anwendungsteile zu generieren. Ein Generator ist allerdings immer nur so gut wie seine Anpassbarkeit. Ein einfaches Feature in diesem Bereich liefert OpenAPI mit seinen import-mappings.
In einem unserer Projekte ist die Grundlage aller unserer Request Objekte eine Basis-Klasse, die technische Information enthält. Diese Informationen sind verpflichtend und aus Sicht der Schnittstelle damit korrekterweise als “required” markiert, was die Generierung in ein TypeScript-Model auch honoriert:
export interface BaseRequest {
transactionId: string;
clientSoftwareVersion: string;
}
export interface SearchRequest extends BaseRequestType{
search: string;
}
Diese technischen Informationen werden nun jedoch nicht aus den fachlichen Komponenten oder Services gesetzt, sondern über einen HTTP Interceptor. Eine einfache fachliche Verwendung dieser Request-Objekte ist nun erst einmal ohne weiteres nicht mehr möglich, weil der Compiler die fehlenden technischen Informationen mit einem Fehler markiert:
let searchRequest: SearchRequest = { // >> missing properties
search: 'lorem ipsum'
}
Um jetzt unsere Typisierung nicht zu torpedieren (“as any”), unsere Schnittstelle aufzuweichen (“required” entfernen) oder boilerplate zu schreiben (Platzhalter Objekte) erlaubt uns OpenAPI über eine entsprechende Konfiguration eigene Objekte in die generierten Models zu integrieren. In unserem Beispiel ist die Lösung denkbar einfach: Wir definieren die Attribute in unserem Fall als optional, da wir über den HTTP Interceptor sicherstellen, dass diese Attribute ohnehin gesetzt werden und ersetzen den generierten BasisTyp durch unseren eigenen:
<pre class="wp-block-syntaxhighlighter-code">export interface BaseRequest {
transactionId?: string; <br /> clientSoftwareVersion?: string;
}</pre>
{
"importMappings": {
"BaseRequestType": "src/app/api/importMappings/baseRequestType"
}
}
(openapi.config.json, beim Aufruf des OpenAPI generators mit zu geben)
Ende Gut. Alles Gut.