Microsoft Kiota | OpenAPI Client Generator Tutorial
TL;DR
Dieses Microsoft Kiota OpenAPI Client Generator Tutorial erklärt, wie OpenAPI-Spezifikationen genutzt werden, um mit Microsoft Kiota automatisch API-Clients in verschiedenen Programmiersprachen zu generieren, Endpunkte auszuwählen und Authentifizierung über IAuthenticationProvider zu implementieren.
Microsoft Kiota in der Welt von OpenAPI
OpenAPI Client Generator Tutorial
Microsoft Kiota bietet spannende Einblicke in die Code-Generierung im Zusammenhang mit OpenAPI-Schnittstellen. Microsoft Kiota ist nicht auf C# und die .NET-Welt beschränkt, sondern ermöglicht die Codegenerierung in diversen Programmiersprachen.
Durchführung
Was ist OpenAPI?
OpenAPI ist ein Standard zur Beschreibung von HTTP-APIs. Früher war dieser Standard auch unter dem Begriff „Swagger Specification“ bekannt. Aktuell befindet sich OpenAPI in Version 3.1.0. Diese ist unter dem Link https://spec.openapis.org/oas/latest.html verfügbar.
Was ist Microsoft Kiota?
Microsoft Kiota ist ein Kommandozeilen-Tool von Microsoft zur Generierung von API-Clients in verschiedenen Programmiersprachen. Zu den aktuell unterstützten Sprachen zählen unter anderem:
- C#
- Go
- Java
- PHP
- Python
- Ruby
- Swift
- TypeScript
Wie installiere ich Microsoft Kiota?
Die Installationsdateien für Microsoft Kiota sind über diesen Link verfügbar. Eine bevorzugte Methode ist die Installation über Visual Studio Code (VS Code). Dazu öffnet man den Extension Manager und sucht nach „Microsoft Kiota“.
In der linken Toolbar erscheint dann ein neuer Menüpunkt, unter dem folgendes Menü angezeigt wird:
Die relevanten Menüpunkte sind „Search“ und „Open API description“. Wenn eine OpenAPI-Schnittstellenbeschreibung als .json-Datei oder per Link verfügbar ist, kann der Pfad zur Datei in das Eingabefenster eingefügt und mit Enter bestätigt werden.
Dies ist jedoch nicht immer der Fall. Nehmen wir an, dass wir für eine API eine Schnittstelle implementieren sollen, jedoch weder die OpenAPI-Schnittstellenbeschreibung vorliegt noch bekannt ist, wo diese zu finden ist. Auch für diesen Fall bietet Kiota eine Lösung, die jedoch mit Vorsicht zu nutzen ist.
Wählt man den Menüpunkt „Search“, öffnet sich ein Eingabefenster, in dem man nach einem Stichwort suchen kann. In meinem Beispiel habe ich nach der Microsoft Graph API gesucht.
Nach Bestätigung der Suche erhält man eine Liste aller von Kiota gefundenen OpenAPI-Schnittstellen.
Hier ist Vorsicht geboten, da unter dem Begriff „Graph“ mehrere verschiedene Schnittstellen gefunden werden können. Da wir in diesem Beispiel den Code für die Microsoft Graph API generieren möchten, wählen wir die entsprechende OpenAPI-Beschreibung aus.
Der Kiota OpenAPI Explorer zeigt anschließend eine Baumstruktur (Tree-View) mit allen verfügbaren Endpunkten an. Diese Ansicht sieht folgendermaßen aus:
Standardmäßig sind alle Endpunkte in der Generierung enthalten. Wenn es Endpunkte gibt, die nicht implementiert werden sollen, kann man diese über den entsprechenden Eintrag von der Generierung ausschließen.
Zum Generieren des API-Clients klickt man in der Toolbar des Kiota OpenAPI Explorers auf den Play-Button.
Ein Wizard führt durch die folgenden Schritte:
- ApiClient: Name des API-Clients
- ApiSDK: Namespace des API-Clients
- Pfad zum Zielverzeichnis des API-Clients
- Programmiersprache
Nach Eingabe und Bestätigung der Informationen dauert die Generierung je nach Größe der API einen Moment.
Wie authentifiziere ich mich bei der API?
Um sich bei der API zu authentifizieren, muss eine Implementierung des IAuthenticationProvider erstellt werden, die je nach API unterschiedlich ist. Im Folgenden ein Beispiel für eine Dummy-Implementierung:
Anschließend wird eine Instanz des HttpClientRequestAdapters benötigt, der als Parameter eine Instanz des IAuthenticationProviders erhält. Der HttpClientRequestAdapter wird verwendet, um den APIClient zu instanziieren. Nach der Instanziierung des APIClients ist die Konfiguration abgeschlossen, und die Implementierung der Business-Cases sowie die Anbindung an die API können beginnen.
Abschluss/Zusammenfassung
Mit Microsoft Kiota erhält man wertvolle Einblicke in die Welt der APIs und die Generierung von API-Clients. Es bleibt abzuwarten, wie sich das Projekt weiterentwickeln wird. Es wäre wünschenswert, wenn Microsoft dieses Tool weiterhin unterstützt, um einen einheitlichen Weg zur Implementierung von OpenAPI-Schnittstellen in Anwendungen zu bieten.
Nützliche Links: Microsoft Kiota Overview
NuGet-Pakete: Microsoft.Kiota.Http.HttpClientLibrary
