
Warum dieser Beitrag?
Das von tarienna entwickelte IoT-Testportal LISAweb bietet eine RESTful API (Application Programming Interface) für Systeme an, die Testdaten direkt in LISAweb anlegen und verwalten möchten. Auf diese Weise kann z.B. bestehende Software für das Management von Testdaten direkt Informationen pflegen ohne die Weboberfläche von LISAweb nutzen zu müssen.
Programmiert ist dieses API mit Spring Boot und wird automatisch mit Hilfe der Swagger UI dokumentiert. Um diese Swagger-Definition zu erstellen, nutzen wir im Projekt SpringFox. SpringFox ist eine Bibliothek für automatisierte JSON-API-Dokumentation für APIs, die mit Spring entwickelt sind.
Die wichtigsten Testinformationen zu einem IoT-Device sind die Information zu den Mobilfunkdaten wie IMEI (International Mobile Station Equipment Identity) die Seriennummer des Funkmoduls, IMSI (International Mobile Subscriber Identity) eine eindeutigen Identifizierung des Netzteilnehmers, ICCID (Integrated Circuit Card IDentifier) die Seriennummer der SIM und die eUICCID bzw. eID (Embedded Universal Integrated Circuit Card IDentifier) die Seriennummer der eSIM. Diese Informationen sind standardisiert und deshalb prüft das LISAweb-API die übertragenen Werte auf syntaktische Korrektheit. Die eUICCID ist z.B. exakt mit 32 Zeichen festgelegt.
Für unsere global agierenden Kunden ergibt sich nun eine Besonderheit, dass z.B. im Markt China keine eUICCID verwendet wird und für diesen Spezialfall die ICCID (mit 20 Zeichen) anstelle der eUICCID gespeichert werden soll.
Ein syntaktischer Validator war schnell geschrieben, doch leider wurde die darin abgebildete Regel von SpringFox nicht erkannt und somit auch nicht in die API-Beschreibung aufgenommen.
SpringFox und individuelle Validatoren
Damit wir die gewünschte Regel zunächst sowohl im LISAweb-API als auch in der LISAweb Applikation nutzen können, wurde ein individueller Validator auf Basis eines regulären Ausdrucks erstellt:
Wird nun ein DTO (Data Transfer Object) erstellt, welches die eUICCID enthält, kann dieser Validator per Annotation verwendet werden:
Verwenden wir dieses DTO innerhalb des RESTful-API, wird die entsprechende Validierung nicht automatisch der generierten API-Dokumentation hinzugefügt und somit auch nicht in der Swagger UI angezeigt. Dem Benutzer der Schnittstelle, also dem Entwickler der Drittanwendung ist es nicht ersichtlich, dass dieses Attribut validiert wird und welche konkrete Überprüfung angewendet wird.
Um dieses Problem zu beheben, haben wie die folgende Komponente unserem Programm-Code hinzugefügt:
Diese 16-Zeilen Code ermöglichen es, dass der Reguläre Ausdruck nach dem die eUICCID innerhalb des LISAweb RESTful-API geprüft wird, nun auch korrekt in der JSON-Definition der Schnittstellen angegeben und somit auch in der Swagger Dokumentation korrekt angezeigt wird.
Dieser Artikel wurde von Philipp Donabauer geschrieben. Philipp ist seit 2019 Teil der tarienna Crew und maßgeblich an der Entwicklung unseres Produktes LISAweb beteiligt.