REST-APIs aus der Konserve
API-Programmcode aus der OpenAPI-Dokumentation generieren
Programmierschnittstellen müssen ordentlich dokumentiert werden, am besten in einer maschinenlesbaren Sprache. Daraus entstehen nicht nur anschauliche Dokumente für menschliche Leser: Den Standard OpenAPI können Sie auch nutzen, um automatisch Code aus der Dokumentation zu erzeugen. Zum Beispiel für das PHP-Framework Laravel.
Zugegeben, komplett von Zauberhand wird aus einer OpenAPI-Dokumentation kein fertiges API und ein Code-Generator macht Entwickler auch nicht überflüssig. Ein solcher Generator kann Ihnen aber eine Menge Fleißarbeit abnehmen. Ganz klassisch schreibt man erst den Code und überwindet sich dann, das fertige API zu dokumentieren. Die Herangehensweise nennt man „Code First“ und sie eignet sich dann, wenn erst nach Fertigstellung jemand nach der Dokumentation fragt. Der meistgenutzte Standard für API-Dokumentationen von REST-APIs heißt OpenAPI, formuliert wird die Doku im YAML-Format. Wie genau eine API-Beschreibung nach OpenAPI 3.0 (OAS) aussieht, haben wir bereits erklärt [1]. Für den Ansatz „Code First“ gibt es einige Unterstützung durch Generatoren. Dann werden relevante Funktionen im Code mit Kommentarblöcken versehen und ein Parser macht daraus eine OAS-Dokumentation.
API First
Populär geworden ist aber auch das gegensätzliche Vorgehen, also „API First“. Ohne dass auch nur eine Zeile Code geschrieben ist, werden die Anforderungen an das API in einer OAS-Beschreibung festgehalten.