Sitegeist.SchemeOnYou
Stets aktuelle OpenApi-Dokumentation direkt aus reinem, typsicherem PHP Code erstellen
In vielen Projekten nutzen wir Schnittstellen, um der Webseite oder auch externen Partnern Daten oder Funktionen bereitzustellen.
Hierbei ergibt sich immer wieder die Frage, welche Daten eigentlich vorkommen können, welche Werte optional sind etc. Während der Erstellung einer Software ist das oft noch intuitiv und für alle klar. Aber spätestens bei der Wartung ergeben sich dann oft Fragen nach Details gefolgt von der nicht immer erfolgreichen Suche nach der Schnittstellen-Dokumentation.
Zur Dokumentation solcher Schnittstellen hat sich der OpenApi-Standard in den letzten Jahren durchgesetzt. Dieser erlaubt es, eine maschinenlesbare Dokumentation zu erstellen. Zusätzlich bietet er mit SwaggerUi auch eine menschenlesbare und komfortabel bedienbare Oberfläche.
Wenn eine solche Dokumentation präzise und wirklich aktuell ist, erlaubt sie sogar Teile des Quelltextes zur Nutzung der Schnittstelle automatisch zu generieren.
Genau an dieser Stelle traten in der Vergangenheit leider immer wieder Qualitätsschwankungen auf - besonders bei externen Schnittstellen. Das ist vor allem deshalb problematisch, weil man zunächst das Problem ausgehend von der Annahme, dass die Dokumentation korrekt ist, analysiert. Erst nach Ausschluss aller anderen Optionen beginnt man, an der Doku zu zweifeln.
Keine Dokumentation zu haben, ist schlimm, aber falsche oder unvollständige Dokumentation ist deutlich schlimmer.
Das wollten wir bei den Schnittstellen, die wir erstellen, gerne vermeiden und daher wurde bei Sitegeist ein internes Projekt mit den folgenden Maßgaben entwickelt:
- Dokumentation aus PHP-Quelltext direkt generieren oder eine bestehende Dokumentation anhand des PHP Quelltext validieren
Bei der Recherche haben wir uns eine Reihe bestehender Lösungen angesehen. Gemeinsamkeit war hier häufig, dass die Dokumentation über Kommentare am Quelltext erstellt wurde. Dadurch bestand leider keinerlei Schutz gegen Abweichungen zwischen Kommentar und Code. Eine solche Lösung erschien uns ,insbesondere anhand der aktuellsten Entwicklung Richtung Type-Safety in der PHP Welt, nicht mehr zeitgemäß. Daher haben wir die Anforderungen ergänzt:
- Alle Informationen werden direkt aus der PHP Sprache abgeleitet und nicht aus Annotationen, die abweichen können.
Hier endete dann leider der ausgetretene Pfad und wir mussten die entsprechende Infrastruktur selbst entwickeln.
Sitegeist.SchemeOnYou
Dieses Paket erlaubt es, Backend-Endpoints sehr einfach zu erstellen indem Methoden PHP-Transfer-Objekte entgegennehmen und auch als Ergebnis zurückgeben. Das SchemeOnYou Paket sorgt dann für die Umwandlung in die JSON-Daten und die Bereitstellung der Dokumentation.
Um dies zu ermöglichen müssen sich die PHP-Transfer-Objekte an einige Regeln halten:
- Readonly Classes mit constructor promoted public properties als DTO
- Readonly Classes mit variadic typed constructor arguments als DTO-Collection
class ProductController extends OpenApiController
{
/*
* Die Methode productListAction ist durch die definition der Typen der Eingabe und Ausgabewerte
* als PHP Objekte strikt definiert und durch statische Anyalyse gut prüfbar
*
* Die Umwandlung der Objekte von / mach JSON und das erstellen der Doku übnernimmz SchemeOnYou
*/
public function productListAction (ProductListQuery $query): ProductList|ProcductListError
{
// business logic
}
}
/*
* Eine DTO Klasse ist readonly und enthält ausschließlich public properties über den
* Konstruktor. Alle Properties müssen DTOs oder DTO-Collections oder simple types sein.
*/
readonly class Product
{
public function __construct (
public ProductIdentifier $identifier,
public string $name,
public Price $price
) {}
}/**
* DTO-Collections sind readonly und haben einen einzigen variadischen Parameter der wiederrum
* einen DTO Typ hat.
*/
readonly class ProductList
{
/**
* @var Product[]
*/
public products;
public function __construct (Product ...$products)
{
$this->products = $products;
}
}Erfahrungen
Seit der Veröffentlichung von SchemeOnYou wurden alle neuen Schnittstellen, die wir für Neos erstellt haben, mit diesem System umgesetzt. Wir sparen bereits viel Zeit bei der Umsetzung der eigentlichen Schnittstelle. Noch mehr Zeit wird bei der Anbindung der Frontend Applikationen gespart, da hier der ClientCode autogeneriert werden kann. Die Wartung der Projekte über die Zeit wird ebenfalls erleichtert, da wir sowohl den PHP- als auch den TypeScript-Teil statisch analysieren können. Insgesamt ein großer Gewinn für alle Beteiligten, die sich nun mehr mit der Verwendung der Daten statt mit dem Austausch befassen können.
Zum Sitegeist.SchemeOnYou Paket
