API-First: Wo ist die Shopware 6 API dokumentiert?

vor 10 Monaten

Wissen Engineering

Shopware 6 ist ein leistungsstarkes E-Commerce-System, das den Fokus auf die API-Schnittstelle legt. Die API-First-Ausrichtung ermöglicht eine nahtlose Integration mit anderen Systemen und bietet Entwicklern die Flexibilität, maßgeschneiderte Lösungen zu entwickeln.

Allerdings gibt es eine Herausforderung: Die offizielle Dokumentation zur API-Schnittstelle ist knapp oder gar nicht vorhanden. Stattdessen gibt es eine umfangreiche automatisch generierte OpenAPI-Datei, die jedoch schwer im Browser zu verwenden ist. Viele Entwickler sind daher auf das Mitschneiden der Kommunikation über die Browserkonsole angewiesen, was weder effizient noch effektiv ist. In diesem Artikel werfen wir einen genaueren Blick auf die Shopware 6 API-Schnittstelle und stellen Ansätze vor, um sie effizient zu nutzen.

Warum ist die API-Schnittstelle wichtig?

Die API-Schnittstelle ist ein wesentlicher Bestandteil eines modernen E-Commerce-Systems. Sie ermöglicht die Kommunikation zwischen verschiedenen Anwendungen und Systemen, wie z.B. externen Apps, ERP-Systemen oder Drittanbieter-Integrationen. Mit der API-Schnittstelle können Entwickler Daten abrufen, bearbeiten und aktualisieren, neue Produkte hinzufügen, Bestellungen verwalten und vieles mehr. Die API-Schnittstelle von Shopware 6 ist die Grundlage für die Erweiterung und Anpassung des Systems nach individuellen Anforderungen.

Die Herausforderung der Dokumentation bei Shopware 6

Leider ist die offizielle Dokumentation zur Shopware 6 API-Schnittstelle begrenzt. Es gibt wenig bis keine spezifischen Anleitungen oder Beispiele, um Entwicklern den Einstieg zu erleichtern. Die vorhandene Dokumentation besteht hauptsächlich aus einer automatisch generierten OpenAPI-Datei, die von einer Entwicklungsversion von Shopware 6 bereitgestellt wird. Jedoch ist diese Datei zu umfangreich, um sie effizient im Browser anzuzeigen. Viele Entwickler haben Schwierigkeiten und beklagen, dass der Browser beim Aufruf der swagger.html abstürzt. Auch wir sind nicht in der Lage, diese Datei normal zu öffnen. Diese Situation erschwert es Entwicklern, schnell und gezielt auf die benötigten Informationen zuzugreifen.

Besonders bei einem API-First Ansatz sollte der Einstieg in das Shopware-Ökosystem und die Erweiterung desselben hohe Priorität haben. Leider hat sich seit der Einführung von Shopware 6 in diesem Bereich kaum etwas getan.

Shopware-Forum: Swagger API Dokumentation zu groß für Browser / Browser stürzt ab

Externer Link, aufgerufen am 06.06.2023. [Im Archiv anzeigen] Mehr erfahren

Alternative Ansätze zur Nutzung der API-Schnittstelle

Angesichts der begrenzten Dokumentation haben viele Entwickler alternative Ansätze entwickelt, um die Shopware 6 API-Schnittstelle effizient zu nutzen.

Entwicklertools des Browsers: Ein häufig verwendetes Vorgehen besteht darin, die Kommunikation des Admin-Panels über die Browserkonsole mitzuschneiden. Dies ermöglicht es Entwicklern, die tatsächlichen API-Anfragen und -Antworten zu sehen und daraus Rückschlüsse auf die verwendeten Endpunkte und Parameter zu ziehen. Obwohl dieser Ansatz funktionieren kann, ist er nicht ideal, da er Zeit und Aufwand erfordert und keine strukturierten Informationen bietet. Insbesondere bei Anpassungen der Endpunkte, sind diese nicht ersichtlich. Hier ist viel manuelle Arbeit erforderlich, wodurch die schnelle Entwicklung für die Shopware 6 Plattform erschwert wird – zumindest für uns.

Einen alternativen OpenAPI-Generator verwenden: Die swagger.html ist eine HTML-Datei, welche durch JavaScript dynamisiert wird. Endpunkte und deren Parameter klappen ein und aus. Es gibt natürlich noch weitere Generatoren. Wir verwenden aktuell einen alternativen OpenAPI-Generator. Dieser erstellt eine statische HTML-Datei, ohne JavaScript. Diese kann bei uns vom Browser besser geöffnet werden. Hier funktioniert auch eine Volltextsuche (STRG+F) nach bestimmten Endpunkten. Schön ist aber anders :-)

Anbei ein Code-Beispiel, wie wir den primitiveren HTML-Generator genutzt haben:

# macOS Paketverwaltung nutzen, um OpenAPI-Generator zu installieren
brew install openapi-generator

# Aufruf des Generators "html"
openapi-generator generate -i www.localhost.local/api/_info/openapi3.json -g html -o ./dist/apidoc/