Spec-First API Entwicklung: Was ist das?

Die meisten API-Fehler sind keine Programmierfehler. Es sind Fehler in der Absprache. Das Frontend erwartete userId, das Backend sandte user_id, und niemand bemerkte es bis zur Qualitätssicherung (QS). Die Spec-First API-Entwicklung behebt dies, indem der Vertrag das erste ist, was Sie schreiben, nicht das letzte, was Sie dokumentieren.

In diesem Leitfaden werden Sie eine kleine OpenAPI-Spezifikation von Hand schreiben und diese einzelne Datei dann verwenden, um Mocks, Tests und Dokumentationen zu generieren, bevor jeglicher Servercode existiert. Der gleiche Ansatz ist unter verschiedenen Namen bekannt: Spec-Driven Development, Design-First oder Contract-First. Sie alle laufen auf dieselbe Idee hinaus: Einigen Sie sich zuerst auf die Schnittstelle, dann bauen Sie sie.

Was Spec-First API-Entwicklung ist

Spec-First API-Entwicklung bedeutet, dass Sie einen maschinenlesbaren Vertrag, normalerweise ein OpenAPI-Dokument, verfassen, bevor Sie den Endpunkt implementieren. Dieser Vertrag beschreibt jeden Pfad, Parameter, Request Body, die Antwortstruktur und den Statuscode. Sobald er existiert, wird er zur Quelle der Wahrheit für alle, die mit der API arbeiten.

Die Spezifikation ist keine Dokumentation, die dem Code hinterherhinkt. Sie führt. Frontend-Teams entwickeln auf Basis eines daraus generierten Mocks. Die Qualitätssicherung (QS) schreibt Tests dagegen. Das Backend implementiert, um sie zu erfüllen. Wenn alle drei mit derselben Datei übereinstimmen, ist die Integration kein Ratespiel mehr.

Dies kehrt die übliche Reihenfolge um. Bei der Code-First-Entwicklung schreiben Sie Handler und beschreiben sie dann nachträglich, oft von Hand, oft innerhalb eines Sprints veraltet. In einem Design-First-Workflow steht die Beschreibung an erster Stelle, und der Code richtet sich danach. Diese eine Änderung verlagert die meisten Integrationsprobleme an den Projektanfang, wo sie kostengünstig zu beheben sind.

Spec-First vs. Code-First Lebenszyklus

Die beiden Ansätze erzeugen die gleichen Endpunkte. Sie unterscheiden sich darin, wann Probleme auftreten und wer parallel mit der Arbeit beginnen kann.

Die rechte Spalte ist der Gewinn. Wenn der Vertrag zuerst existiert, hören drei Teams auf, sich gegenseitig zu blockieren, und beginnen, auf einer gemeinsamen Definition aufzubauen.

Ein ausgearbeitetes OpenAPI-Beispiel

Entwerfen wir Schritt für Schritt einen kleinen /users-Endpunkt. Wir werden ihn in Teilen erstellen, damit jeder Teil klar ist, und dann die vollständige Datei zusammenfügen.

Beginnen Sie mit dem Dokumentkopf. Dieser deklariert die OpenAPI-Version und grundlegende Metadaten.

openapi: 3.0.3
info:
 title: Users API
 version: 1.0.0
servers:
 - url: https://api.example.com/v1

Definieren Sie als Nächstes das User-Schema unter components. Die einmalige Definition ermöglicht es Ihnen, es überall zu referenzieren, sodass die Struktur über Anfragen und Antworten hinweg konsistent bleibt.

components:
 schemas:
 User:
 type: object
 required: [id, email, createdAt]
 properties:
 id:
 type: string
 format: uuid
 email:
 type: string
 format: email
 name:
 type: string
 createdAt:
 type: string
 format: date-time

Fügen Sie nun den Pfad GET /users hinzu. Er listet Benutzer auf und unterstützt einen limit-Abfrageparameter. Beachten Sie, wie die Antwort das User-Schema mit $ref wiederverwendet, anstatt es neu zu definieren.

paths:
 /users:
 get:
 summary: List users
 operationId: listUsers
 parameters:
 - name: limit
 in: query
 schema:
 type: integer
 default: 20
 maximum: 100
 responses:
 "200":
 description: A list of users
 content:
 application/json:
 schema:
 type: array
 items:
 $ref: "#/components/schemas/User"

Fügen Sie den POST /users-Vorgang hinzu, um einen Benutzer zu erstellen. Der Request Body definiert, was der Client senden muss, und die 201-Antwort gibt den erstellten Datensatz zurück.

 post:
 summary: Create a user
 operationId: createUser
 requestBody:
 required: true
 content:
 application/json:
 schema:
 type: object
 required: [email]
 properties:
 email:
 type: string
 format: email
 name:
 type: string
 responses:
 "201":
 description: User created
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/User"
 "400":
 description: Invalid request body

Das ist ein vollständiger, gültiger Vertrag. Er benennt jedes Feld, markiert email als erforderlich, begrenzt limit auf 100 und deklariert sowohl die Erfolgs- als auch die Fehlerantworten. Noch niemand hat eine Zeile Servercode geschrieben, aber die Vereinbarung ist festgeschrieben.

Mocks, Tests und Dokumentationen aus der Spezifikation generieren

Der Grund, die Spezifikation zuerst zu schreiben, ist die Hebelwirkung. Eine Datei steuert drei Artefakte, die Teams normalerweise separat erstellen.

Mocks. Ein Mock-Server liest Ihre Spezifikation und gibt Beispielantworten zurück, die jedem Schema entsprechen. Die Hinweise format: uuid und format: email ermöglichen es Tools, realistische Beispieldaten zu generieren. Ihr Frontend ruft GET /users auf und erhält am ersten Tag ein wohlgeformtes Array von Benutzern, lange bevor der echte Handler existiert. Wenn sich die Spezifikation ändert, ändert sich der Mock mit ihr.

Tests. Da die Spezifikation erforderliche Felder, Typen und Statuscodes deklariert, dient sie auch als Testorakel. Vertragstests stellen sicher, dass die echte Antwort für POST /users einen 201 mit einem Body zurückgibt, der dem User-Schema entspricht, und einen 400, wenn email fehlt. Sie erfinden keine Behauptungen. Sie überprüfen, ob die Implementierung dem entspricht, worauf Sie sich bereits geeinigt haben.

Dokumentationen. Die API-Referenzdokumentation wird direkt aus der Spezifikation gerendert. Jeder Endpunkt, Parameter und jedes Beispiel, das Sie in der Dokumentation sehen, stammt aus derselben YAML-Datei. Es gibt keine zweite Kopie, die synchron gehalten werden muss, sodass die Dokumentation nicht vom Vertrag abweichen kann.

Dies ist auch der Grund, warum Spec-First gut zu einem Git-nativen API-Workflow passt: Die Spezifikation ist eine einfache Textdatei, sodass jede Vertragsänderung als überprüfbarer Diff in einem Pull Request sichtbar wird. Ein Prüfer kann sehen, dass jemand email umbenannt oder ein erforderliches Feld entfernt hat, bevor es ausgeliefert wird.

So geht's in Apidog

Apidog unterstützt dies End-to-End durch den Spec-First-Modus. Anstatt die OpenAPI-Datei als Export zu behandeln, betrachtet sie die Datei als Projekt. Sie bearbeiten die YAML direkt, und der Rest des Arbeitsbereichs folgt.

Sie schreiben oder fügen die /users-Spezifikation in den Editor ein. Apidog parst sie und startet sofort einen Mock-Server für beide Operationen, sodass Ihr Frontend beginnen kann, diese aufzurufen. Die generierte Dokumentation aktualisiert sich, während Sie tippen. Wenn Sie bereit sind, die Implementierung zu überprüfen, führen Sie die Operationen der Spezifikation als Testfälle gegen Ihr echtes Backend aus und bestätigen, dass die Antworten den Schemas entsprechen.

Der Teil, der dies zuverlässig macht, ist die bidirektionale Git-Synchronisierung. Ihre Spezifikation lebt in einem Repository, und Änderungen fließen in beide Richtungen. Bearbeiten Sie die YAML in Ihrem Editor und pushen Sie sie, und Apidog übernimmt sie. Bearbeiten Sie in Apidog, und die Änderung landet als Commit, den Ihr Team überprüfen kann. Der Vertrag lebt niemals an zwei Orten gleichzeitig. Wenn Sie einen tieferen Vergleich wünschen, wie sich dies zu einem reinen Design-First-Ansatz verhält, siehe Spec-First vs. Design-First in Apidog.

Eine Spec-First-Checkliste

Verwenden Sie dies, bevor Sie eine Spezifikation als bereit zum Implementieren betrachten:

• Die Spezifikation ist fehlerfrei gegen das OpenAPI-Schema validiert.
• Jeder Endpunkt deklariert seine Erfolgs- und mindestens eine Fehlerantwort.
• Gemeinsame Strukturen befinden sich in components/schemas und werden mit $ref referenziert, nicht kopiert.
• Erforderliche Felder sind als required markiert, und Formate (uuid, email, date-time) sind dort gesetzt, wo sie zutreffen.
• Die Spezifikationsdatei ist in der Versionskontrolle committet und in Pull Requests überprüft.
• Ein Mock-Server läuft aus der Spezifikation, und das Frontend kann ihn ansprechen.
• Vertragstests überprüfen echte Antworten anhand der deklarierten Schemas.
• Die veröffentlichten Dokumentationen werden aus derselben Datei gerendert, ohne manuell gepflegte Kopie.

Wenn jedes Kästchen angekreuzt ist, können Ihre Teams parallel auf Basis einer Vereinbarung statt dreier Mutmaßungen arbeiten.

FAQ

Ist Spec-First API-Entwicklung dasselbe wie Design-First?

Meistens ja. „Design-First“ und „Contract-First“ beschreiben dasselbe Prinzip: Schreiben Sie die Schnittstelle vor der Implementierung. „Spec-First“ ist der wörtlichste Name, da die OpenAPI-Spezifikationsdatei das konkrete Artefakt ist, mit dem Sie beginnen. In der Praxis werden die Begriffe synonym verwendet.

Muss ich YAML von Hand schreiben?

Nein. Sie können die Spezifikation in einem visuellen Editor erstellen und ihn die YAML erzeugen lassen, oder Sie schreiben die YAML direkt, wenn Sie dies bevorzugen. Der Punkt ist nicht das Format, das Sie eingeben, sondern dass der Vertrag existiert und vor dem Code vereinbart wird. Viele Teams mischen beides: sie entwerfen visuell und verfeinern in YAML während der Überprüfung.

Wie verhindere ich, dass Spezifikation und Code auseinanderdriften?

Machen Sie die Spezifikation zur Quelle der Wahrheit und setzen Sie sie durch. Halten Sie die Spezifikation in Git, damit Änderungen als Diffs überprüft werden können. Führen Sie Vertragstests in der CI aus, damit der Build fehlschlägt, wenn eine Antwort nicht mehr dem Schema entspricht. Mit der bidirektionalen Synchronisierung bleiben Bearbeitungen an beiden Stellen abgeglichen, was die häufigste Ursache für Abweichungen beseitigt.

Spec-First API-Entwicklung ist eine kleine Änderung in der Reihenfolge mit einer großen Auswirkung. Schreiben Sie den Vertrag, einigen Sie sich darauf, und bauen Sie dann danach. Wenn Sie den gesamten Workflow ausprobieren möchten, öffnen Sie den Spec-First-Modus in Apidog und verweisen Sie ihn auf Ihr Repository.