Dokumentieren und testen Sie eine API aus ihren Anwendungsfällen

Geschätzte Lesezeit : 3 min · Veröffentlicht 2026-10-01

Wählen Sie Aufgaben vor Adressen

Listenverwendungen wie das Auffinden eines Produkts, das Lesen der Verfügbarkeit, das Aktualisieren eines Datensatzes oder die Verfolgung der Verarbeitung. Definieren Sie autorisierte Personen und Systeme für jeden Vorgang. Eine öffentliche Lese-API und eine administrative API haben unterschiedliche Zugriffsanforderungen.

Bereiten Sie ein Anfrage- und Antwortbeispiel für jede wesentliche Aufgabe mithilfe von synthetischen Werten und erklärten Feldern vor. Unterscheiden Sie stabile Kennungen, Etiketten, Einheiten und Daten. Definieren Sie fehlende Daten, anstatt plausible Werte für unbekannte Informationen zu ersetzen.

einen expliziten Vertrag beschreiben

OpenAPI bietet ein sprachunabhängiges Beschreibungsformat für HTTP-APIs, das Operationen, Parameter, Antworten und Modelle abdeckt. Wählen Sie eine Version aus, die von Ihren Tools unterstützt wird, und bewahren Sie das Dokument mit dem Projekt auf. Die neueste Version passt nicht automatisch zu jeder Toolchain.

Beschränkungen der Dokumentnutzung, Paginierung, Filter, Bestellung, Fehler und leere Antworten. Behandeln Sie Cors nicht als Nachweis der Zulassung. Überprüfen Sie den Betrieb und die Zugriffskontrollen auf Objektebene mit dem technischen Team.

Grenzen und Berechtigungen testen

Versuchen Sie es mit einem vorhandenen Objekt, einem fehlenden Objekt, einem ungültigen Parameter und einer Liste, die länger als eine Seite ist. Überprüfen Sie die nächste Seite auf Verluste oder Wiederholungen innerhalb des gewählten Aktualisierungsmodells. Zustandsbeschränkungen, die die API nicht garantieren kann.

Verwenden Sie Testkonten mit unterschiedlichen Berechtigungen. Der Versuch liest und ändert sich außerhalb des zulässigen Umfangs mithilfe von synthetischen Daten. Zeichnen Sie erwartete Status und nützliche Nachrichten auf, ohne interne Traces oder Konfigurationsgeheimnisse freizulegen.

Planänderung und Unterstützung

Unterscheiden Sie ein hinzugefügtes Feld von einem entfernten Feld oder einer geänderten Bedeutung. Identifizieren Sie Verbraucher vor einer inkompatiblen Änderung. Erläutern Sie die Übergangszeit und wie Sie Integrationen erkennen können, die noch den früheren Vertrag verwenden.

Liefern Sie ein ausführbares Beispiel für eine Testumgebung, eine Testmatrix und einen technischen Kontakt. Beziehen Sie beobachtete Fehler nach der Freigabe auf dokumentierte Beispiele. Die auf den Idealfall beschränkte Dokumentation lässt Integratoren ohne Anleitung für Ablehnungen und Unterbrechungen.

Primärdokumentation: OpenAPI-Initiative – Spezifikation.

Referenzdokumente

OpenAPI-Initiative – Spezifikation · Quelle eingesehen 2026-10-16

Inhalt aktualisiert 2026-10-16

Funktionale Validierungsmatrix zur Projektanpassung

Diese vorgeschlagenen Kontrollen verwenden fiktive Fälle. Entscheiden Sie, welches Verhalten mit dem Team zu erwarten ist, schreiben Sie das Ergebnis auf und weisen Sie vor der Veröffentlichung ungelöste Abweichungen zu.

Scrollen Sie die Tabelle horizontal, um alle Spalten zu lesen. Mit der Tastatur fokussieren Sie den Tabellenbereich und verwenden die Pfeiltasten.

Testfälle, erwartete Ergebnisse und nützliche Beweise
Fall	Erwartetes Ergebnis	Beweis zu behalten
vorhandene und fehlende Ressourcen	Jedes Ergebnis stimmt mit dem dokumentierten Status- und Antwortmodell überein.	Anfrage, Antwort und entsprechendes Vertragsbeispiel aus der Testumgebung erfasst.
Parameter außerhalb des Bereichs	Die Ablehnung ist verständlich und stellt keine interne Stack-Trace offen.	Öffentliche Nachricht und Ergebnis in der Akzeptanzmatrix beibehalten.
Zwei Berechtigungsstufen	Eine verbotene Ressource bleibt auch mit einer bekannten Kennung unzugänglich.	Vergleichen Sie die Ergebnisse mit zwei synthetischen Konten mit explizit unterschiedlichen Berechtigungen.
Paginierung und Filterwechsel	Token-Handling und Reise-Neustart-Verhalten werden definiert.	Bestellung, zurückgegebene Kennungen und Regeln, die beim Ändern des Filters angewendet werden.

Häufig gestellte Fragen

Reicht die generierte Dokumentation aus, um eine API zu testen?

Es hilft beim Lesen eines Vertrages, aber Berechtigungen, fehlende Daten, Fehler, Listen und Änderungen müssen weiterhin getestet werden. Vergleichen Sie Beispiele mit den tatsächlichen Antworten der Testumgebung.

Ersetzt CORS die Zugriffsberechtigungen?

Nein. Die originellen Regeln ersetzen nicht die Operations- und Objektberechtigungen des Dienstes. Beschreiben Sie diese Berechtigungen und testen Sie die serverseitige Durchsetzung mit Testkonten.

Verwandte Themen

Entwicklung und Code verstehen