CapMDM Feature Update: OpenAPI

Neuigkeiten

• OpenAPI-Vorlagen als neuer Designelementtyp erlauben nun die Generierung von einsatzfertigen OpenAPI-Beschreibungen
• OpenAPI Servicebeschreibungen enthalten nun eine Dokumentation der Querysyntax für die Suche nach Properties.
• Services die eine BLOB-Property bereitstellen erzeugen nun einen Blob-spezifischen Endpunkt in der OpenAPI-Beschreibung.
• Der Datentyp des id-Parameters für Single-Item Endpunkte wurde auf string geändert. Das ist nur eine Korrektur der OpenAPI-Beschreibung, die Implementierung war immer ein String.

OpenAPI-Vorlagen im Detail

CapMDM erzeugt automatisch OpenAPI-konforme Servicebeschreibungen aus Ihrem Datenmodell und den CapMDM-Servicedefinitionen. Das erspart mühevolle Handarbeit, erhöht so auch die Qualität und ermöglicht die umgehende produktive Nutzung von neuen Services und Serviceänderungen.

So funktioniert es bisher

CapMDM verwendet beim Generieren von OpenAPI-Beschreibungen zunächst die Informationen aus Ihren Servicedefinitionen, also insbesondere:

• relative URL und Version
• erlaubte HTTP-Methoden
• Propertynamen und ihr Mapping zu CapMDM Attributdefinition oder einer OQL-Query.

Aus den CapMDM Entitäts- und Attributdefinitionen werden dann Datentypen, Constraints und Beschreibungsfelder bezogen und eine OpenAPI-Beschreibung erzeugt.

Der nächste Schritt

Die von CapMDM generierten Servicebeschreibungen benötigen bisher noch manuelle Ergänzungen, um wirklich alles abzudecken. Das sind insbesondere Informationen über verschiedene Serverumgebungen, Ansprechpartner, SLA- und Authentifizierungsinformationen.

Diese Informationen werden bei unseren Kunden entweder in CapMDM oder auch ganz anderen Infrastrukturkomponenten festgelegt, z.B. API-Gateways oder einem Service-Mesh.

Dennoch ist es wünschenswert, direkt aus CapMDM vollständig automatisch OpenAPI-Beschreibungen erzeugen die dann auch keiner Nachbearbeitung mehr bedürfen. Wir haben daher einen Designelementtyp ergänzt: die OpenAPI Vorlage.

So funktioniert es

Eine solche Vorlage im JSON-Format können Sie für jeden CapMDM Katalog getrennt anlegen und darin alles eintragen, was in einer OpenAPI-Servicebeschreibung Platz findet. Beim Generieren einer OpenAPI-Beschreibung sucht CapMDM nach einer solchen Vorlage und fügt die von CapMDM generierten Inhalte ein.

So definieren Sie administrative und Zugriffsinformationen nur einmal pro Katalog, generieren danach bei jeder Serviceänderung neu und erhalten sets einsatzfertige Servicebeschreibungen..

Schritt 1:

Schritt 2:

CapMDM erzeugt ein mit typischen Elementen vorbefüllte Vorlage, die Sie nur noch ergänzen müssen - an den Stellen an denen Sie das möchten. Speichern und fertig. Die Vorlage wird bei jeder OpenAPI-Generierung erneut gesucht und angewendet.

Mehrere Vorlagen?

Wenn Sie in einem Katalog z.B. mit unterschiedlichen Ansprechpartnern für Gruppen von Services arbeiten, können Sie für jede Servicegruppe Gruppe einen eigenen Katalog für die Servicedefinitionen anlegen.