Jede API hat eine Dokumentation, die niemand von vorn bis hinten liest. Eine OpenAPI-Spezifikation kann Hunderte Zeilen lang sein und Pfade, Methoden, Request- und Response-Formen sowie die Ressourcen beschreiben, auf denen sie arbeiten. Sie ist präzise und vollständig und fast unmöglich im Kopf zu behalten. Was du eigentlich willst, wenn du bei einem neuen Service landest, ist ein Bild: Was sind die Hauptressourcen, welche Endpunkte greifen auf sie zu und wie hängt das alles zusammen?
Dieses Bild steckt bereits in der Spezifikation. Ein OpenAPI-Dokument oder etwas Ähnliches sind strukturierte Daten, also kann ein Tool sie lesen und die Form zeichnen, die du sonst von Hand rekonstruieren müsstest.
Was dir die Spezifikation schon verrät
Ein sauberes API-Dokument enthält mehr Struktur, als man ihm ansieht. Daraus kannst du ableiten:
- Ressourcen, aus den Schemas und den Pfadsegmenten (users, orders, products).
- Operationen, aus den Methoden jedes Pfads (auflisten, anlegen, ändern, löschen).
- Beziehungen, aus Schema-Referenzen (eine Order verweist auf einen User und auf Line Items).
- Gruppierung, aus Tags, die meist den echten Modulen des Service entsprechen.
Das als Text zu lesen, ist langsam. Es als Diagramm zu sehen, geht sofort, und im Diagramm passiert der „ach, so hängt das zusammen“-Moment.
Der Ablauf
Es ist wirklich Einfügen und Loslegen. Gib dem Tool dein OpenAPI-Dokument, und es extrahiert die Ressourcen und Beziehungen und legt sie als editierbare Formen an. Danach kommt das übliche Formen: nach Tag gruppieren, die Kernressource hervorheben, die Endpunkte ausblenden, die für dieses Diagramm nur Rauschen sind.
Die Spezifikation ist die Quelle der Wahrheit für die API. Wenn das Diagramm daraus generiert wird, können Bild und Vertrag sich nicht widersprechen.
Warum ableiten statt zeichnen
Du könntest ein API-Diagramm von Hand zeichnen, und es wäre falsch, sobald jemand den nächsten Endpunkt hinzufügt. Wenn du es aus der Spezifikation ableitest, ist das Bild an den Vertrag gebunden. Ändert sich die API, generierst du neu, und das Diagramm ist in Sekunden wieder aktuell. Bei einem Service, der sich weiterentwickelt, ist das der Unterschied zwischen einer Dokumentation, der man vertraut, und einer, die man still ignoriert.
Über einen einzelnen Service hinaus
Dieselbe Idee skaliert. Wenn du mehrere Services mit je eigener Spezifikation hast, kannst du eine übergeordnete Karte bauen: Welcher Service besitzt welche Ressourcen, und wo ruft einer den anderen auf? Das ist das Diagramm, das nie jemand von Hand aktuell halten kann, und genau das, das dir während eines Incidents einen Nachmittag spart. Lass die Spezifikationen es zeichnen und forme es dann zu der Ansicht, die dein Team braucht.
Hör auf, YAML zu lesen, um einen Service zu verstehen. Füge die Spezifikation ein und lies stattdessen das Bild.