OpenAPI Specification / SwaggerHub – nett gemeint und meistens gut

Fast jeder Entwickler der sich im Web bewegt, wird derzeit früher oder später Kontakt mit der OpenAPI Initiative  machen. Ziel ist es die Spezifikation von (primär REST)-Schnittstellen zu vereinheitlichen und dabei eine Version zu erzeugen die auch maschinenlesbar ist. Damit eröffnen sich viele Möglichkeiten zur Validierung, Dokumentation und wo nötig auch Code-Generierung wenn man entsprechende Frameworks einsetzt und externe Rest-APIs anspricht. Soweit so gut.

Die Spezifikation ist mittlerweile recht umfangreich und beschreibt sehr viele der Use-Cases recht gut. Insbesondere die Methodik zur Beschreibung von Endpunkten ist in meinen Augen wirklich gut gelungen. Nun gilt aber wie immer: Wo Licht ist, ist auch Schatten. Gerade im Umfeld der Schema-Definitionen bin ich auf eine Lästigkeit gestoßen, für die ich noch keine wirklich brauchbare Lösung gefunden habe. Im Wesentlichen geht es dabei um dynamische indizierte Arrays bzw. Objekte. Continue reading