Git-Native API Workflow: Definition & Erstellung

Ihr Code liegt in Git. Ihre CI-Pipelines, Reviews und Release-Historie liegen in Git. Warum sollte Ihre API-Spezifikation also woanders liegen?

Ein Git-nativer API-Workflow hält Ihre OpenAPI-Definition am selben Ort wie Ihren Code. Sie bearbeiten die Spezifikation als einfache YAML- oder JSON-Datei, committen sie und führen sie durch denselben Review-Prozess, den Sie für alles andere verwenden. Keine separate Cloud-Datenbank. Kein Export-Import-Hin-und-Her. Die Spezifikation ist einfach eine weitere Datei in Ihrem Repository.

Button

Was ein Git-nativer API-Workflow bedeutet

Ein Git-nativer API-Workflow behandelt Ihre API-Spezifikation als Code. Die OpenAPI-Datei befindet sich in einem Repository neben Ihren Diensten. Jede Änderung ist ein Commit. Jeder Commit hat einen Autor, eine Nachricht und einen Diff.

Dies bietet Ihnen drei Dinge, die Sie bereits vom Quellcode erwarten:

• Versionshistorie. Sie können sehen, wer einen Endpunkt wann geändert hat. git blame funktioniert für Ihre Spezifikation.
• Branching und Review. Spezifikationsänderungen durchlaufen Pull Requests. Reviewer sehen den genauen Diff, bevor etwas zusammengeführt wird.
• Eine einzige Quelle der Wahrheit. Die Datei in main ist der Vertrag. Tools, Dokumente und Mocks lesen alle daraus.

Dies ist die Kernidee hinter einem Spec-First API-Workflow: Die Spezifikation führt, und die Implementierung folgt. Für einen tieferen Einblick in diese Praxis lesen Sie unseren Leitfaden zur Spec-First API-Entwicklung.

Der entgegengesetzte Ansatz speichert Ihre Spezifikation in einer proprietären Cloud-Anwendung. Das funktioniert, bis Ihr Team wächst oder Ihr Prozess reift. Dann zeigen sich die Schwächen.

Das Problem mit Cloud-gebundenen API-Spezifikationen

Die meisten API-Design-Tools speichern die Spezifikation in ihrer eigenen Datenbank. Sie bearbeiten sie über deren Benutzeroberfläche. Die „Datei“, die Sie zu besitzen glauben, ist eigentlich eine Zeile im System eines anderen.

Dies führt auf vorhersehbare Weise zu Problemen.

Reviews finden an zwei Stellen statt. Codeänderungen durchlaufen GitHub. Spezifikationsänderungen durchlaufen ein separates Tool mit eigenen Kommentaren und eigener Historie. Reviewer wechseln den Kontext. Genehmigungen geraten aus dem Gleichschritt.

Der Diff ist verborgen. Wenn die Spezifikation in einer Cloud-Datenbank liegt, können Sie keinen sauberen Zeilen-für-Zeilen-Diff in Ihrem Pull Request sehen. Sie genehmigen eine „v3 des Designs“, ohne zu wissen, was sich tatsächlich geändert hat.

Der Export wird zur lästigen Pflicht. Um die Spezifikation in CI zu integrieren, exportieren Sie sie, committen den Export und hoffen, dass niemand die Cloud-Kopie in der Zwischenzeit bearbeitet hat. Zwei Wahrheitsquellen, ein unvermeidlicher Konflikt.

Automatisierung kämpft gegen Sie. Linters, Vertragstests und Code-Generatoren wollen eine Datei auf der Festplatte. Eine Cloud-gebundene Spezifikation erzwingt einen Abrufschritt, bevor dies alles ausgeführt wird.

Die Behandlung Ihrer API-Spezifikation als Code beseitigt all dies. Die Datei ist die Spezifikation. Git ist die Historie. Ihre bestehende Pipeline erledigt den Rest. Wir behandeln das Prinzip detailliert in API-Spezifikation als Code.

Wie der Apidog Spec-First-Modus funktioniert

Der Spec-First-Modus wurde für Teams entwickelt, die bereits in Commits und Branches denken. Sie entwerfen die API als rohe YAML- oder JSON-Dateien, und Apidog hält diese Dateien bidirektional mit Ihrem Git-Repository synchron.

Das erhalten Sie:

Ein IDE-ähnlicher OpenAPI-Editor

Sie schreiben die Spezifikation in einem Code-Editor, nicht in einem Formular. Der Editor bietet die Annehmlichkeiten, die Sie von einer IDE erwarten würden:

• Syntax-Highlighting für YAML und JSON.
• Validierung gegen die OpenAPI- und Swagger-Schemas, sodass Fehler bereits beim Tippen angezeigt werden.
• Auto-Vervollständigung für OpenAPI-Keywords, -Typen und -Referenzen.

Sie behalten die Kontrolle über die genaue Datei. Keine versteckten Felder, keine UI-spezifischen Metadaten.

Rohe YAML/JSON-Dateien

Die Spezifikation ist eine echte Datei. Ein kleiner Ausschnitt davon:

openapi: 3.1.0
info:
 title: Orders API
 version: 1.2.0
paths:
 /orders/{orderId}:
 get:
 summary: Get an order by ID
 operationId: getOrder
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 properties:
 id:
 type: string
 status:
 type: string
 enum: [pending, shipped, delivered]

Dies ist die Datei, die in Ihrem Repository landet. Was Sie bearbeiten, wird committet.

Eine automatisch geparste, navigierbare Gliederung

Während Sie tippen, parst Apidog die Datei und erstellt eine visuelle Gliederung in der linken Seitenleiste. Pfade, Operationen und Schemas erscheinen als anklickbarer Baum. Sie erhalten gleichzeitig die Lesbarkeit eines Design-Tools und die Präzision von Rohdateien.

Lange Spezifikationen bleiben navigierbar. Springen Sie zu einem Endpunkt, ohne Hunderte von Zeilen durchscrollen zu müssen.

Bidirektionale Git-Synchronisierung

Der Spec-First-Modus verbindet sich mit Ihrem Git-Provider und synchronisiert Änderungen in beide Richtungen. Er unterstützt GitHub und GitLab direkt und Azure DevOps über eine Git-Verbindung.

Ziehen Sie Änderungen, die Ihre Teamkollegen gepusht haben. Bearbeiten Sie lokal im Apidog-Editor. Committen und pushen Sie dann zurück in denselben Branch. Das Repository und Ihr Arbeitsbereich bleiben synchron.

Commit, Push und ein Synchronisierungsstatus-Indikator

Sie müssen Apidog nicht verlassen, um Git zu verwalten. Stagen Sie Ihre Änderungen, schreiben Sie eine Commit-Nachricht und pushen Sie. Ein Synchronisierungsstatus-Indikator zeigt Ihnen, wo Sie stehen. Nach einem erfolgreichen Push steht dort etwas wie „Gerade synchronisiert“. Wenn Sie es sich vor dem Pushen anders überlegen, können Sie nicht gepushte Änderungen verwerfen und zum letzten synchronisierten Zustand zurückkehren.

Diese bidirektionale Synchronisierung ist das Herzstück des Git-nativen API-Workflows. Für eine detaillierte Anleitung zur GitHub-Seite siehe OpenAPI-Spezifikation mit GitHub synchronisieren.

Einrichtungs-Walkthrough

So gelangen Sie von einem leeren Repository zu einer synchronisierten Spezifikation. Die vollständige Referenz finden Sie in den Spec-First-Modus-Dokumenten.

• Erstellen Sie ein Projekt aus einem Repository. Starten Sie in Apidog ein neues Spec-First-Projekt und verbinden Sie Ihren Git-Provider. Wählen Sie das Repository, das Ihre API-Spezifikation enthält, und wählen Sie den zu verfolgenden Branch, normalerweise main. Apidog zieht die vorhandenen Spezifikationsdateien in den Editor.

• Bearbeiten Sie die Spezifikation. Öffnen Sie die OpenAPI-Datei im Editor. Fügen Sie einen Endpunkt hinzu, passen Sie ein Schema an oder korrigieren Sie eine Antwort. Syntax-Highlighting, Validierung und Auto-Vervollständigung leiten Sie beim Schreiben. Die Gliederung in der linken Seitenleiste aktualisiert sich, sobald sich die Datei ändert.
• Verfolgen Sie geänderte, hinzugefügte und gelöschte Dateien. Apidog zeigt an, welche Dateien Sie seit der letzten Synchronisierung geändert haben. Geänderte, hinzugefügte und gelöschte Dateien werden markiert, sodass Sie genau wissen, was in den Commit aufgenommen wird.

• Schreiben Sie eine Commit-Nachricht. Beschreiben Sie die Änderung in einfacher Sprache, genau wie Sie es in jedem Git-Client tun würden. „404-Antwort zu getOrder hinzufügen“ ist besser als „Spezifikation aktualisieren“.
• Pushen. Senden Sie den Commit an den verfolgten Branch. Ihre Teamkollegen und Ihre CI-Pipeline sehen nun die neue Version.

• Prüfen Sie „Gerade synchronisiert“. Beobachten Sie, wie der Synchronisierungsstatus-Indikator den Push bestätigt. Wenn dort „Gerade synchronisiert“ steht, stimmen Ihre lokalen Bearbeitungen und der Remote-Branch überein. Von hier aus durchläuft die Änderung Ihren normalen Pull-Request- und Review-Prozess.

Das ist der vollständige Zyklus: Pull, Bearbeiten, Commit, Push, Verifizieren. Kein Exportschritt. Keine zweite Wahrheitsquelle.

Spec-First- vs. Design-First-Modus

Apidog unterstützt zwei Arbeitsweisen. Der Unterschied liegt darin, wo die Spezifikation gespeichert wird und wie Sie sie bearbeiten.

Keiner der Modi ist „besser“. Sie bedienen unterschiedliche Gewohnheiten. Wenn Ihr Review- und Release-Prozess bereits auf Git läuft, eliminiert der Spec-First-Modus die Bruchstelle. Wenn Ihr Team visuell entwirft und selten rohe OpenAPI-Spezifikationen bearbeitet, passt der Design-First-Modus möglicherweise besser.

Wann sollte man es verwenden?

Greifen Sie zum Spec-First-Modus, wenn:

• Ihre Spezifikation Pull Requests und Code-Reviews durchlaufen soll.
• Sie git blame und eine echte Commit-Historie für Ihren API-Vertrag wünschen.
• Ihre CI-Pipeline Spezifikations-Linting, Vertragstests oder Code-Generierung ausführt, die eine Datei auf der Festplatte benötigen.
• Mehrere Ingenieure die Spezifikation bearbeiten und Sie saubere, zusammenführbare Diffs wünschen.
• Sie es leid sind, von einem Tool in ein anderes zu exportieren.

Bleiben Sie bei einem visuellen, Cloud-First-Ansatz, wenn Ihr Team APIs entwirft, ohne rohe OpenAPI zu schreiben, oder wenn Nicht-Ingenieure die Spezifikation besitzen und einen formularbasierten Editor bevorzugen.

FAQ

Was ist ein Git-nativer API-Workflow?

Ein Git-nativer API-Workflow speichert Ihre OpenAPI-Spezifikation als Datei in einem Git-Repository und verwaltet jede Änderung durch Commits, Branches und Pull Requests. Die Spezifikation folgt dem gleichen Review- und Versionskontrollprozess wie Ihr Anwendungscode, sodass es eine einzige Wahrheitsquelle gibt.

Unterstützt der Apidog Spec-First-Modus GitHub und GitLab?

Ja. Der Spec-First-Modus synchronisiert bidirektional direkt mit GitHub und GitLab. Azure DevOps wird über eine Git-Verbindung unterstützt. Sie verbinden das Repository, wählen einen Branch, und Apidog hält Ihre Bearbeitungen und den Remote-Zustand synchron.

Kann ich OpenAPI-Dateien als rohes YAML oder JSON bearbeiten?

Ja. Der Spec-First-Modus bietet Ihnen einen IDE-ähnlichen Editor für rohes YAML und JSON, mit Syntax-Highlighting, Schema-Validierung und Auto-Vervollständigung für OpenAPI und Swagger. Eine Gliederung in der linken Seitenleiste parst die Datei automatisch, sodass Sie schnell durch große Spezifikationen navigieren können.

Was ist der Unterschied zwischen dem Spec-First- und dem Design-First-Modus?

Der Spec-First-Modus speichert Ihre Spezifikation als Dateien in Git und bearbeitet sie in einem Code-Editor mit bidirektionaler Synchronisierung. Der Design-First-Modus speichert die Spezifikation in einem Apidog-Cloud-Projekt mit einem visuellen, formularbasierten Editor. Wählen Sie Spec-First, wenn Ihr Workflow bereits auf Git basiert.

Fazit

Ein Git-nativer API-Workflow beendet die Trennung zwischen Ihrem Code und Ihrem API-Vertrag. Die Spezifikation wird zu einer Datei, die Datei zu einem Commit, und der Commit durchläuft den Review-Prozess, dem Sie bereits vertrauen.

Der Apidog Spec-First-Modus bietet Ihnen den IDE-ähnlichen Editor, die navigierbare Gliederung und die bidirektionale Git-Synchronisierung, um dies zu verwirklichen. Sie bearbeiten rohes YAML oder JSON, committen eine klare Nachricht, pushen und sehen, wie der Status „Gerade synchronisiert“ anzeigt.

Probieren Sie den Spec-First-Modus aus und bringen Sie Ihre API-Spezifikation nach Hause zu Git.

Button