Erfahren Sie in diesem Tutorial, wie Sie die OpenAPI Spezifikation definieren, um eine konsistente und genaue Dokumentation Ihrer RESTful-APIs mit OpenAPI 3.0 zu gewährleisten.
Benötigen Sie Hilfe bei der Entwicklung und Dokumentation von APIs für große oder komplexe Projekte? Keine Angst! Wir haben genau die richtige Lösung für Sie – die OpenAPI-Spezifikation (früher bekannt als Swagger-Spezifikation). Dieser kostenlose Open-Source-Standard macht die API-Entwicklung und -Dokumentation zum Kinderspiel! Mit OpenAPI können Sie APIs ganz einfach in einem standardisierten Format erstellen und dokumentieren, das leicht zu verstehen ist.
Sparen Sie Zeit bei der Erforschung komplexer API-Entwicklung und -Dokumentation. Wir helfen Ihnen, den Prozess mit OpenAPI zu vereinfachen!
Was ist die OpenAPI-Spezifikation (OAS)
OpenAPI ist eine Spezifikation, die die Struktur einer RESTful API definiert und ihre Funktionen beschreibt. Die OpenAPI-Spezifikation bietet eine Standardmethode zum Dokumentieren und Interagieren mit APIs, sodass Entwickler herausfinden und verstehen können, wie sie effizient funktionieren. Die RESTful APIs verwenden das HTTP-Protokoll zur Datenübertragung, sodass Plattformen und Systeme, die in verschiedenen Programmiersprachen geschrieben sind, problemlos miteinander kommunizieren können.
Mit OpenAPI benötigen Sie keinen Zugriff auf den Quellcode oder eine Überprüfung des Netzwerkverkehrs, um zu verstehen, wie eine API funktioniert. Die API-Definition selbst liefert alle Informationen, die Sie benötigen.
OpenAPI-Format
Die neueste Version von OpenAPI ist 3.0 . OpenAPI-Definitionen können in JSON oder YAML geschrieben werden. JSON stellt Daten mithilfe von Schlüssel-Wert-Paaren dar, anstatt eine langatmige API-Beschreibung zu schreiben und der OpenAPI-Struktur zu folgen. Dadurch sind die Funktionen einer API leicht zu verstehen, selbst wenn Sie keinen Zugriff auf den Quellcode oder die Dokumentation haben.
Beispiel einer OpenAPI 3.0-Spezifikation im JSON-Format:
In einer herkömmlichen Dokumentation würden Sie beispielsweise für jede API-Methode einen separaten Abschnitt schreiben, in dem beschrieben wird, was sie tut und wie sie verwendet wird. OpenAPI verfolgt einen anderen Ansatz, indem diese Informationen in einer Reihe von Schlüssel-Wert-Paaren organisiert werden. Jede Methode verfügt über eine Reihe von Eigenschaften, die sie beschreiben, darunter Anforderungsparameter und Antwortcodes.
Während JSON das Standardformat für OpenAPI ist, können Sie auch YAML verwenden , eine einfachere Auszeichnungssprache. Damit wird das Erstellen und Bearbeiten von OpenAPI-Dokumenten noch einfacher.
Das sind also die Grundlagen von OpenAPI. Anfangs mag es etwas technisch erscheinen, aber wenn Sie den Dreh erst einmal raus haben, werden Sie sich fragen, wie Sie jemals ohne ausgekommen sind.
Die OpenAPI-Spezifikation verwendet JSON-Datentypen, die in der JSON-Schemaspezifikation definiert sind. Zu diesen Datentypen gehören Ganzzahlen, Zahlen, Boolesche Werte und Zeichenfolgen. Sie können das Format dieser Datentypen auch mit der Eigenschaft „Format“ ändern , z. B. int32, int64, Float, Double, Binär, Daten, Datum/Uhrzeit und Kennwortformat. OpenAPI ermöglicht auch die Verwendung von Modellen (Objekten), die unter der JSON-Spezifikation als Schemaobjekte definiert sind.
OpenAPI-Struktur
Die OpenAPI-Spezifikation ist ein Dokument, das die Struktur und das Verhalten von REST-APIs beschreibt. Lassen Sie uns tiefer in das OpenAPI-Dokument eintauchen.
Ein OpenAPI-Dokument hat ein strukturiertes Format, das aus Objekten oder Objektarrays besteht, die verwandte Schlüssel-Wert-Paare gruppieren. Der erste Satz Klammern {} in einem OpenAPI-Dokument enthält alle Eigenschaften und wird als „Dokumentobjekt“ bezeichnet . Obwohl eine gewisse Flexibilität besteht, müssen OpenAPI-Dokumente einer grundlegenden Struktur folgen. Einige Abschnitte auf hoher Ebene sind obligatorisch, während andere optional sind, sodass Variationen in den OpenAPI-Spezifikationen zwischen verschiedenen APIs möglich sind.
Ein OpenAPI-Dokument kann die folgenden Abschnitte enthalten:
- OpenAPI: Die API erfordert die Angabe der OpenAPI-Version, damit Tools die OpenAPI-Spezifikation analysieren und Dokumentation generieren können.
- Info: Dieses Feld enthält Metadaten zur API, wie etwa Titel, Beschreibung und Version. Verschiedene Tools können diese Informationen nutzen.
- Server: Dieses Feld in der OpenAPI-Spezifikation besteht aus einem Array von Serverobjekten, von denen jedes eine URL für den Serverhost und eine kurze Beschreibung des Servers enthält. Diese Informationen liefern Verbindungsdetails, die Sie zur Interaktion mit dem Server verwenden können.
- Pfade: Dieses Objekt enthält die relativen Pfade zu den einzelnen Endpunkten der API. Jeder Pfad enthält verfügbare Operationen zur Interaktion mit der API, wie POST, GET, PUT oder DELETE.
- Komponenten: Dieses Feld in der OpenAPI-Spezifikation ist ein Objekt, das wiederverwendbare Schemata für Anforderungstexte, Antwortschemata und Sicherheitsschemata enthält. Auf diese Schemata kann in der gesamten Spezifikation mit dem Tag $ref verwiesen werden, insbesondere im Pfadobjekt.
- Sicherheit: Ein Objekt, das den Typ des Sicherheitsschemas deklariert, das Anfragen autorisiert. Ein Sicherheitsobjekt wird global definiert oder durch einzelne Vorgänge überschrieben.
- Tags: Ein Objekt mit Metadaten, die die Reihenfolge angeben, in der Sie API-Ressourcen in der Dokumentation anzeigen sollen.
- ExternalDocs: Ein Objekt, das auf zusätzliche Dokumentationen wie etwa Benutzerhandbücher verweist.
Hier ist die grundlegende Vorlage für ein OpenAPI-Dokument mit den erforderlichen Feldern im YAMLJSON-Format.
POST-Anforderung
Der folgende Beispielendpunkt für eine POST-Anfrage zum Hochladen eines Bildes eines Haustiers ist definiert.
Sie können den obigen Codeausschnitt unter https://editor.swagger.io/ ausführen . Die Ausgabe lautet wie folgt:
Der Codeausschnitt liefert zunächst grundlegende Informationen zur API, wie etwa Titel und Version. Außerdem wird die Basis-URL für den API-Server angegeben.
Der Abschnitt „Tags “ definiert einen Tag namens „pet“, der alle Endpunkte im Zusammenhang mit Haustieren gruppiert. Der Abschnitt „Pfade “ enthält die Definition für den Endpunkt /pet/{petId}/uploadImage .
Der Endpunkt /pet/{petId}/uploadImage unterstützt eine POST-Methode zum Hochladen eines Bilds für ein Haustier. Der Parameterabschnitt definiert zwei Parameter, „petId“ und „additionalMetadata“, die die zu aktualisierende Haustier-ID bzw. alle zusätzlichen Metadaten für das hochgeladene Bild angeben.
Der Abschnitt „Anforderungstext“ gibt die Struktur des Anforderungstexts an, der im Binärformat vorliegen sollte. Der Abschnitt „Antworten“ definiert einen einzelnen Antwortcode, 200, der den erfolgreichen Vorgang angibt.
Was sind die Vorteile von OpenAPI?
Die OpenAPI-Spezifikation bietet Entwicklern, die APIs erstellen und dokumentieren, mehrere Vorteile.
Die OpenAPI-Spezifikation rationalisiert die API-Entwicklung durch bessere Zusammenarbeit, Konsistenz, Codegenerierung, Validierung und Tools. Eine standardisierte und transparente Methode zur Beschreibung von APIs vereinfacht die effektive Zusammenarbeit von Teams und gewährleistet gleichzeitig die Konsistenz der API-Dokumentation.
Entwickler können Code für APIs in mehreren Programmiersprachen generieren und dabei die Konsistenz zwischen den Sprachen wahren. Die generierten Dokumentationsdateien sind zuverlässig und konsistent und sparen Entwicklern Zeit.
Validierungstools helfen, Kompatibilität zu gewährleisten und Fehler zu vermeiden, während ein umfangreiches Ökosystem an Tools den gesamten API-Entwicklungsprozess optimiert. Die OpenAPI-Spezifikation reduziert Fehler und verbessert die Qualität der resultierenden Softwareprojekte.
So erstellen Sie eine OpenAPI-Spezifikation
Aber was, wenn Sie es vorziehen, Code nicht manuell zu schreiben? Kein Problem, wir helfen Ihnen weiter! Apidog ist ein Tool, das die Arbeit mit der OpenAPI-Spezifikation zum Kinderspiel macht. ist eine Cloud-basierte Plattform, die das Entwerfen, Testen und Veröffentlichen von APIs vereinfacht. Damit können Entwickler OpenAPI-Spezifikationen mithilfe eines intuitiven visuellen Editors erstellen und bearbeiten.
Apidog enthält außerdem integrierte Tests, mit denen Entwickler ihre APIs direkt von der Plattform aus testen können. bietet einen API-Marktplatz, auf dem Entwickler vorgefertigte APIs anderer Entwickler entdecken und verwenden können. Damit können Sie Ihren APIs mithilfe einer intuitiven Benutzeroberfläche schnell Pfade, Parameter und Antworten hinzufügen.
Und das Beste daran? Apidog generiert automatisch Dokumentation. Mit nur wenigen Klicks können Sie eine ansprechende Dokumentation für Ihre API basierend auf der OpenAPI-Spezifikation erstellen. Die Dokumentation enthält Informationen zu jedem Endpunkt, einschließlich seiner Parameter, Antworten und Beispiele.
Sehen wir uns Schritt für Schritt an, wie das geht. Hier ist ein Schritt-für-Schritt-Prozess zum Importieren einer OpenAPI-Spezifikationsdatei in Apidog:
Schritt 1. Öffnen Sie die Apidog-Website
Öffnen Sie zunächst die Apidog-Website in Ihrem Webbrowser. Sie können darauf zugreifen, indem Sie deren Website besuchen .
Schritt 2. Melden Sie sich bei Ihrem Konto an
Wenn Sie bereits ein API Dog-Konto haben, melden Sie sich an, indem Sie oben rechts auf der Seite auf die Schaltfläche „Anmelden“ klicken . Wenn Sie kein Konto haben, können Sie eines erstellen, indem Sie auf die Schaltfläche „Registrieren“ klicken und den Anweisungen folgen.
Schritt 3. Ein neues Projekt erstellen
Klicken Sie nach der Anmeldung auf die Schaltfläche „Projekt erstellen“, um ein neues Projekt zu erstellen.
Schritt 4. OpenAPI-Datei importieren
Importieren Sie auf der Projekterstellungsseite eine OpenAPI-Spezifikationsdatei. Klicken Sie auf die Schaltfläche „Importieren“, um fortzufahren.
Schritt 5. Laden Sie Ihre OpenAPI-Datei hoch:
Auf der Importseite sehen Sie ein Feld, in das Sie die URL Ihrer OpenAPI-Datei eingeben können. Wenn Sie keine URL haben, können Sie die Datei von Ihrem lokalen Computer hochladen, indem Sie auf die Option „oder Datei hochladen“ klicken und die Datei auswählen.
Eingabe der URL meiner JSON-Datei.
Schritt 6. Warten Sie, bis der Import abgeschlossen ist
Abhängig von der Größe und Komplexität Ihrer OpenAPI-Datei kann der Importvorgang einige Minuten dauern.
Apidog analysiert die Datei automatisch und generiert eine neue API in Ihrem Konto.
Schritt 7. Konfigurieren Sie Ihre API-Einstellungen
Nach dem Importieren der OpenAPI-Datei werden Sie auf die Einstellungsseite für Ihre neue API weitergeleitet. Auf dieser Seite können Sie verschiedene Einstellungen konfigurieren, z. B. den Namen, die Beschreibung und die Authentifizierungsanforderungen Ihrer API.
Mehr lesen: So verwenden Sie die Discord API: Eine umfassende Anleitung
Schritt 8. Beginnen Sie mit dem Erstellen Ihrer API
Nachdem Sie Ihre API-Einstellungen konfiguriert haben, können Sie mithilfe der intuitiven Benutzeroberfläche von Endpunkte und Dokumentation zu Ihrer API hinzufügen.
Indem Sie die einfachen Schritte zum Importieren einer OpenAPI-Spezifikationsdatei in Apidog befolgen, können Sie Ihre API-Projekte effizienter verwalten und dokumentieren. Die Spezifikationsdatei enthält normalerweise wichtige Details wie den POST-Endpunkt, den Pfad, die Parameter und die Antwortcodes.
Nachdem Sie Ihre Spezifikationsdatei zu Apidog hinzugefügt haben , können Sie dessen benutzerfreundliche API und leistungsstarke Tools nutzen, um Konsistenz und Zuverlässigkeit in Ihrem API-Entwicklungsprozess sicherzustellen. Wenn Sie also Zeit sparen und Ihren API-Entwicklungsprozess optimieren möchten, sollten Sie die OpenAPI-Spezifikation mit Apidog verwenden.