Was ist OpenAPI?
SmartBear, die Muttergesellschaft von Swagger:
“Die OpenAPI Spezifikation (OAS) definiert einen Standard, eine sprache-agnostische Schnittstelle zu RESTful APIs, die es sowohl Menschen als auch Computern ermöglicht, ohne Zugriff auf Quellcode, Dokumentation oder durch Netzverkehrsprüfungen die Fähigkeiten des Dienstes zu entdecken und zu verstehen.”
Das ist ja ein großer Worthappen! Lassen Sie uns SmartBears Beschreibung in kleinere Häppchen aufteilen:
1. “…definiert einen Standard…”:
- Die OpenAPI Spezifikation definiert die Struktur einer API, die auch die API beschreibt.
2. “…eine sprache-agnostische Schnittstelle zu RESTful APIs…”:
- REST-APIs verwenden das HTTP-Protokoll für die Datenübertragung. Dieses Protokoll ermöglicht Plattformen und Systeme, die in verschiedenen Programmiersprachen geschrieben sind, miteinander zu interagieren.
- OpenAPI behandelt nur RESTful APIs, nicht andere APIs.
3. “…, der es Menschen und Computern ermöglicht, die Fähigkeiten des Dienstes…”:
- Menschen können die Dokumentation direkt aus der OAS-Definition einer API lesen.
- Ein Client versteht, wie er Anfragen senden kann und wie API-Server basierend auf der API-Definition auf diese Anfragen reagieren.
4. “…ohne Zugriff auf Quellcode, Dokumentation oder durch Netzverkehrsprüfungen.“
- Mit OpenAPI werden die Client-Anwendung und der API-Server getrennt. Die API-Definition eines Dienstes legt fest, wie Clients mit ihm interagieren können, ohne dass der Client seinen Quellcode lesen muss.
- Zusammenfassend lässt sich sagen, dass OpenAPI eine RESTful API Spezifikation ist, die APIs beschreibt, die der RESTful Architektur entsprechen. Eine Spezifikation stellt eine Schnittstelle zur Verfügung, mit der Menschen und Computer eine API verstehen und mit ihr interagieren können.
Geschichte von OpenAPI
Die Ursprünge von OpenAPI beginnen mit dem Ingenieur Tony Tam von der Firma Wordnik im Jahr 2009. Tony erstellte eine Spezifikation (damals Swagger genannt), die Wordniks Online-Wörterbuch JSON API beschreibt.
In den nächsten Paar Jahren machte Swagger mehrfach von Tony geleiteten Iterationen durch. Allerdings hat Swagger 2.0 einen Anstieg bei der Annahme der Spezifikation festgestellt und die Schaffung von Werkzeugen zur Analyse der Spezifikation ausgelöst.
Im Jahr 2015 wurde Swagger von SmartBear erworben. SmartBear ist das Unternehmen, das derzeit Swagger besitzt. Die Swagger-Spezifikation wurde in „OpenAPI“ umbenannt, um die neue OpenAPI-Initiative zu reflektieren. Diese Umbenennung ist der Grund, warum „Swagger“ mit dem „OpenAPI“-Standard verwechselt wird.
Zu dieser Zeit erkannte eine Unternehmensgruppe, dass die Branche eine herstellerneutrale und standardisierte Art der Beschreibung von APIs benötigt. Die Branche musste der Branche „Best Practices“ anbieten und Updates für OpenAPI im Laufe der Zeit überwachen.
Diese Unternehmen gründeten die OpenAPI Initiative als Governance-Programm unter der Linux Foundation, die den OpenAPI Standard pflegt und praktische Anleitung bietet. Die Gründungsfirmen, die die OpenAPI Initiative gründeten, waren CapitalOne, PayPal, SmartBear, IBM, 3Scale, Google, Apigee, Intuit, Microsoft und Restlet. Seitdem ist die Zahl der an der Initiative beteiligten Unternehmen erheblich gestiegen.
Der Technische Lenkungsausschuss verwaltet nun OpenAPI und veröffentlicht weiterhin neue Versionen basierend auf Community-Feedback.
Warum ist OpenAPI ein beliebter Standard?
Es gibt mehrere Spezifikationen, die RESTful APIs beschreiben. OpenAPI gehört zu den bekanntesten und am weitesten verbreiteten Anwendungen. Die anderen beiden Formate, die für REST-APIs verwendet werden, sind RAML und API Blueprint. Später werden wir die Vor- und Nachteile von OpenAPI im Vergleich abdecken. Während OpenAPI als Industriestandard betrachtet werden kann, wählen Unternehmen am Ende oft das Format, das ihren geschäftlichen Bedürfnissen am besten entspricht.
Daher stellt sich die Frage: wenn es mehrere Formate gibt, um REST-APIs zu beschreiben, warum ist OpenAPI so besonders? Ein Schlüsselfaktor dafür, warum OpenAPI so beliebt ist, ist seine Annahme. Mehr Adoption führt zu mehr Unterstützung durch die Gemeinschaft, zu robusterenInstrumenten und einer effektiveren Kontrolle.
Ein Unternehmen kann die Open API-Spezifikation für seine Portabilität und Einfachheit verwenden. OpenAPI ist „language-agnostic“ und definiert eine gemeinsame Sprache für die Client-Server-Kommunikation. Es ist sehr kompatibel mit Systemen, die in verschiedenen Programmiersprachen geschrieben sind. OpenAPI ist auch für Menschen und Computer sehr lesbar und hat die Unterstützung einer großen, wachsenden Gemeinschaft.
Ein weiteres beliebtes Format ist RAML, eine API-Modellierungssprache, die sich auf API-Definition und -Design konzentriert (obwohl man APIs mit OpenAPI entwerfen kann). Die Funktionen von RAML könnten als Zwerge von OpenAPI erscheinen. Es hat den Vorteil, hierarchisch zu sein und Datenmodellvererbung zu unterstützen. RAML ist jedoch nicht so weit verbreitet wie OpenAPI. Obwohl RAML eine engagierte Community hat, hat es weniger Unterstützung für die Gemeinschaft. RAML hat Werkzeuge, aber es gibt einige Hinweise, dass bei der neuesten Version die notwendige Unterstützung fehlt.
Zusätzlich zu RAML ist API Blueprint eine weitere Alternative zu OpenAPI. API Blueprint konzentriert sich auf klare Dokumentation, die sich im Gegensatz zu JSON (wie OpenAPI) oder YAML (wie OpenAPI und RAML) auf Markdown Format stützt. Aufgrund seiner geringen Annahme fehlt es API Blueprint an Unterstützung für die Community und an robusten Werkzeugen für OpenAPI. Die Integration der API Blueprint in Ihren gesamten API-Lebenszyklus ist schwierig, da der einzige Schwerpunkt auf Dokumentation liegt.
Zusammenfassend ist OpenAPI der beliebteste Standard für die Beschreibung von APIs. Obwohl es Nachteile hat, wird OpenAPI wahrscheinlich in der Annahme wachsen, während die langfristige Lebensfähigkeit anderer Spezifikationstypen unsicher ist.
Wie definiert OpenAPI eine API?
Denken Sie an ein Legacy-Spezifikationsdokument, das Sie im Format Microsoft Word (.docx) lesen würden. Dieses Dokument stellt den breiten Kontext eines Systems dar und beschreibt seine Komponenten und Interaktionen mit anderen Systemen.
Die Struktur der alten Spezifikationen ist oft unterschiedlich. Eine API-Spezifikation, wie OpenAPI, ist streng strukturiert. Wenn eine API-Spezifikation einem anderen Format entspricht, wie RAML oder API Blueprint, hat die Dokumentation eine Struktur, die diesem Format entspricht.
Wenn Sie auf die Definition von OpenAPI zurückkommen, hören Sie oft die synonymen Begriffe „Spezifikation“ und „Definition“. Eine API-Spezifikation definiert eine API. Beim Lesen einer API-Spezifikation erfahren Sie, welche Art von Anfragen Sie senden können und welche Antworten Sie von der API erhalten möchten. Zusätzlich beschreibt die Spezifikation die verfügbaren Optionen, die die zurückgegebenen Informationen beeinflussen. Wie eine Legacy-Spezifikation erfahren Sie über ein System, seine Komponenten und seine Wechselwirkungen.
Ein weiterer Unterschied zwischen alten Spezifikationen und API-Spezifikationen besteht darin, dass API-Spezifikationen dynamisch sind. Wann auch immer sich der zugrunde liegende Quellcode einer API ändert, aktualisiert sich die Dokumentation. Legacy-Spezifikationsdokumente erfordern eine manuelle Aktualisierung der Word-Dokumente, wenn sich das System ändert.
OpenAPI Format
Bevor Sie die Struktur einer OpenAPI-Spezifikation verstehen, müssen Sie das Format eines OpenAPI-Dokuments verstehen. Anders als in Word geschriebene, alte Spezifikationen ist OpenAPIs Format JSON. Während eine Diskussion der Nuancen von JSON für diesen Blog-Beitrag außer Bereich ist, könnten Sie JSON als eine Möglichkeit betrachten, die Daten einer API als Schlüssel-Wert-Paare zu repräsentieren.
Zum Beispiel in älteren Spezifikationen schreiben Sie den Titel einer Spezifikation (einschließlich des Namens des Systems) unter Verwendung eines Titelstils auf der Titelseite. Um den Titel einer Open API-Spezifikation zu schreiben, schreiben Sie den Titel als JSON-Schlüsselpaar.
Denken Sie nun an alle Informationen über eine API. Seine Methoden, Operationen, Antworten, etc. Stellen Sie sich diese Eigenschaften vor, die in einer Reihe dieser Schlüssel-Wert-Paare dokumentiert sind, die der OpenAPI-Struktur folgen.
Hinweis: Während JSON das Standardformat für OpenAPI ist, ist es möglich, OpenAPI in einfacherem YAML darzustellen (ein Abkürzungszeichen, das für YAML ist keine Markup-Sprache).
Datentypen
Als JSON-Objekt unterstützt die OpenAPI-Spezifikation Datentypen, die in der breiteren JSON-schematischen Spezifikation definiert sind. Primitive beinhalten Integer, Zahlen, Booleans und Zeichenketten. Sie können das Format eines Datentyps mit dem Modifikator-Eigenschaft Format angeben. Zum Beispiel können Sie eine Ganzzahl als int32 oder int64 Format angeben, eine Zahl als float oder double, oder eine Zeichenkette als Binär-, Daten-, Datums- oder Kennwortformat. OpenAPI unterstützt auch Modelle (Objekte), die in der breiteren JSON-Spezifikation als Schema-Objekte definiert sind.
Es ist wichtig zu beachten, dass JSON das primäre Format REST-APIs ist, die zum Senden und Empfangen von Informationen verwendet werden.
Struktur
Bisher verstehen wir, dass:
- eine OpenAPI Spezifikation ein JSON-Objekt ist.
- die Eigenschaften einer API eine Reihe von Schlüssel-Wert-Paaren sind.
- Werte Datentypen sind, die durch die breitere JSON-Spezifikation definiert werden.
Jetzt ist es an der Zeit, über die Struktur von OpenAPI zu diskutieren.
Wie bereits erwähnt, ist ein OpenAPI-Dokument streng strukturiert. Objekte oder Arrays von Objekten gruppieren bezogene Schlüssel-Wert-Paare. Die hochstufigen Objekte einer OpenAPI-Spezifikation sind wie die Kapitel eines alten Spezifikationsdokuments.
Unten ist ein OpenAPI Vorlage mit eingeklappten Abschnitten, um die Gesamtstruktur anzuzeigen. Jeder Abschnitt hat Eigenschaften, oder Schlüssel-Wert-Paare, die Metadaten über die API liefern.
Die obere Ebene von OpenAPI, angegeben durch die ersten Klammern { }, wird als „Dokument Objekt“ bezeichnet, da es alle OpenAPI Eigenschaften enthält.
Während OpenAPI Dokumente einer grundlegenden Struktur entsprechen müssen, bietet OpenAPI eine gewisse Flexibilität. Einige der High-Level-Abschnitte sind erforderlich, andere nicht. Sie werden OpenAPI-Spezifikationen für verschiedene APIs bemerken, die etwas anders aussehen.
Ein OpenAPI-Dokument kann die folgenden Abschnitte enthalten:
- Openapi – Ein Pflichtfeld, das die OpenAPI Spezifikationsversion der API definiert. Werkzeuge verwenden die Versionsnummer, um beispielsweise die OpenAPI Spezifikation zu analysieren, um Dokumentation zu generieren.
- Info – Ein Pflichtfeld, das Metadaten enthält. Die Werkzeuge können Metadaten auf unterschiedliche Art und Weise einsetzen.
- Servers – Ein Array von Serverobjekten. Jedes Serverobjekt enthält die Verbindungsdetails zu einem Server. Dieses Objekt enthält die URL zum Server Host und eine Beschreibung des Servers.
- Paths – Ein Pflichtobjekt, das die relativen Pfade zu den einzelnen Endpunkten der API enthält. Ein vorgegebener Pfad verfügt über Operationen zur Interaktion mit der API wie POST, GET, PUT oder DELETE.
- Components – ein Objekt, das wiederverwendbare Schemas für Request-Bodys, Response-Schemas und Security-Schemata enthält. Schemas in diesem Abschnitt werden in bestimmten Teilen der Spezifikation referenziert, wie dem Pfadobjekt, mit dem Tag $ref.
- Security – ein Objekt, das die Art des Sicherheitssystems erklärt, das Anfragen autorisiert. Ein Sicherheitsobjekt wird global definiert oder durch einzelne Operationen überschrieben (security scheme override).
- Tags – ein Objekt mit Metadaten. Werkzeuge, die die Spezifikation analysieren, können dieses Objekt nutzen. Sie können zum Beispiel die Reihenfolge angeben, in der jede API-Ressource in Ihrer API-Dokumentation angezeigt werden soll (statt in alphabetischer Reihenfolge).
- ExternalDocs – ein Objekt, das Links zu zusätzlichen Dokumentationen bereitstellt. Sie können dieses Objekt verwenden, um einen Link zu Ihren Benutzeranleitungen hinzuzufügen.
Schemas
Am Ende Ihrer API-Dokumentation, gibt es typischerweise einen Schema-Abschnitt, der den Schemas entspricht, die im Komponentenabschnitt der API-Definition beschrieben sind.
Dieser Abschnitt ist ein schnelles Glossar, wenn der Leser allgemeine Schemas im breiteren Kontext der API anzeigen muss (nicht deren Verwendung in bestimmten Operationen). Schemas sind Objekte, die Eigenschaften/Metadaten enthalten.
Der folgende Schema-Abschnitt für den Swagger Petstore zeigt Spektralschemas an. Order ist ein Schema, das eine Bestellung für ein Haustier im Swagger Petstore darstellt. Jede Bestellung hat ihre Metadaten inklusive ID, das Datum der Versendung und den Status der Bestellung.
Stärken von OpenAPI
OpenAPI hat folgende Vorteile:
- Leere Dokumentation – OpenAPI ist bekannt für seine leicht lesbare Dokumentation für Menschen und Computer.
- Language-agnostic – Clients können mit API-Servern interagieren, ohne die Implementierung des Servers zu kennen. Andere Formate wie die API Blueprint benötigen einen Code von Drittanbietern auf dem Server und stellen keinen Code für Sie bereit.
- Governance – Die OpenAPI-Initiative behält den OpenAPI-Standard und wird von Branchenführern moderiert.
- Weit verbreitete Aufnahme – OpenAPI ist das beliebteste Format für die Beschreibung von REST-APIs. Das Ausmaß seiner Annahme deutet darauf hin, dass OpenAPI auf die Dauer bleibt. Eine Spezifikation wie die API Blueprint leidet unter mangelnder Adoption.
- Robuste Werkzeuge – Das am meisten unterstützte Format – es gibt jetzt eine Verbreitung von Tools, die OpenAPI für die Erstellung von Dokumentation, Testing, etc. nutzen. Bei anderen Spezifikationen fehlt die Unterstützung und Wartung von OpenAPI für die Werkzeugbearbeitung.
Schwächen von OpenAPI
Jeder Spezifikationstyp hat seine Stärken und Schwächen. Hier werden wir uns auf die Nachteile von OpenAPI im Vergleich zu seinem nächsten Konkurrenten RAML konzentrieren.
Weniger nützlich für API-Design und Planung
Sie können einen „spec-first“-Ansatz wählen, um eine API basierend auf OpenAPI zu entwerfen. Dieser Ansatz beinhaltet das Schreiben der OpenAPI-Spezifikation für eine API „von Hand“ oder die Verwendung eines Designwerkzeugs. Mit diesem Ansatz entwerfen Sie eine API-Spezifikation und nutzen dann die Spezifikation als „Vertrag“ beim Bau der API. Das Gegenteil von „spec-first“ ist die Verwendung von OpenAPI zur Erstellung von Dokumentationen, ohne es als Design-Werkzeug zu verwenden.
Obwohl der „spec-first“-Ansatz viele Vorteile hat, kommt OpenAPI normalerweise nicht vor der API-Entwicklung.
Die hierarchische Struktur von RAML kann sich als Planungs- und Konstruktionswerkzeug vermehren. Daher kann RAML den „spec-first“-Ansatz mehr unterstützen als REST. Letztendlich wird RAML als „Datenmodellierung“ und API „Beschreibung“ vermarktet, während Swagger das Letztere ist. Auf das hierarchische Modell von RAML wird im nächsten Abschnitt näher eingegangen.
Nicht Hierarchisch
Eines der Kernkonzepte für API-Definitionsstandards wie OpenAPI und RAML ist die Fähigkeit, Datenobjekte zu erstellen und miteinander zu verbinden. OpenAPI verwendet hierfür Schemas und unterstützt JSON eingebaute Datentypen. RAML verwendet ein Typsystem, um assoziierte Eigenschaften zu speichern und die Wiederverwendung über die gesamte Bandbreite hinweg zu fördern. Es unterstützt auch die gleichen eingebauten Datentypen wie OpenAPI.
OpenAPI hat keine „echte“ hierarchische Struktur. Was möchten Sie aus einer hierarchischen Struktur, die Ihre API beschreibt? Idealerweise wollen Sie ein System zur Verknüpfung Ihrer Datenmodelle, das:
- leicht lesbar/verständlich ist,
- die Definition von Beziehungen zwischen Datenmodellen mittels Vererbung erlaubt,
- Wiederholung gemeinsamer Eigenschaften reduziert,
- und die Wiederverwendbarkeit des Codes maximiert.
Das RAML-Typsystem ist als System noch hierarchischer als REST. Laut RAMLs Readme auf GitHub minimiert der Einsatz von „Ressourcentypen und Merkmalen“ von RAML die Wiederholung in einem RESTful API-Design und fördert die Konsistenz innerhalb und über APIs. Als nächstes werden wir uns mit dem RAML-Typsystem detaillierter beschäftigen.
Unterstützt keine Vererbung von Datenmodellen
Die Objekttypen von RAML können andere Objekttypen vererben. Obwohl OpenAPI Schemas „referenzieren“ können, unterstützt es technisch keine Vererbung wie RAML. Ich sage „technisch“, weil Sie ein Schema mit einem anderen verknüpfen können, indem Sie eine Schema-Referenz verwenden ( $ref Tag). RAML geht jedoch noch einen Schritt weiter. Sie können Beziehungen zwischen Datenmodellen aufbauen und die Wiederholung gemeinsamer Eigenschaften vermeiden. Bei OpenAPI sind Schemas nicht hierarchisch wie RAML miteinander verknüpft. RAML-Typen haben eine „echte“ Vererbung und können Eltern-Kind-Beziehungen zwischen Datenmodellen aufbauen.
Kein „visuelles“ Werkzeug
Der Einsatz von RAML als Datenmodell macht ihn visueller und leichter lesbar als OpenAPI. Sie können leicht die Beziehung zwischen den Typen und ihren gemeinsamen Eigenschaften sehen.
RAML als visuelleres Werkzeug fördert die langfristige Planung von Dingen wie Mock-Server-Antworten, API-Konsolen und mehr. Es könnte auch bei der Antizipierung und Planung von zukünftigen API-Verbesserungen mit RAML hilfreich sein.
Fehlende Unterstützung für andere Architekturen
Nur OpenAPI kann RESTful APIs beschreiben. RAML hat den zusätzlichen Vorteil, andere Architekturen außer REST zu unterstützen wie RPC oder SOAP, solange sie das HTTP-Protokoll verwenden. Die Flexibilität von RAML erlaubt es Ihnen, es als Dokumentationswerkzeug für Architekturen neben REST zu verwenden.
Beispiel von OpenAPI – Swagger Petstore
Die beste Methode, OpenAPI zu lernen ist ein praktischer Ansatz. Bestimmte Tools erlauben es Ihnen, OpenAPI-Spezifikationen zu bearbeiten und dann API-Dokumentation zu generieren. Die Swagger Petstore Spezifikation ist ein Beispiel für ein OpenAPI Dokument.
SwaggerUI ist ein Tool, das eine API-Definition analysiert, um Dokumentation zu generieren. SwaggerUI hat einen browserbasierten Editor (unten angezeigt). Sie können mit dem SwaggerUI-Editor experimentieren
Auf der linken Seite ist die OpenAPI-Spezifikation im YAML-Format sichtbar. Wenn Sie Änderungen an der Spezifikation vornehmen, erzeugen diese Änderungen neue Dokumentation im rechten Fenster. Das rechte Panel ist das Swagger-Dokument, das direkt aus der OpenAPI-Spezifikation für das Petstore (Panel auf der linken Seites) generiert wird. Zum Beispiel führt das Ändern der Beschreibung eines Pfades dazu, dass das Swagger-Dokument mit den neuen Änderungen aktualisiert wird.
Wenn Sie Swaggers OpenAPI spec auf der linken Seite betrachten, sehen Sie alle Sektionen, die in diesem Blog-Artikel beschrieben sind, einschließlich openapi, info, servers, paths, components, tags, etc.
Swagger erzeugt eine Fehlermeldung, wenn Sie von der OpenAPI-Struktur abweichen oder etwas Ungültiges eingeben. Die Fehlerbehandlung von Swagger betont den Ansatz, dass Sie das OpenAPI-Format beachten müssen, damit die Dokumentation korrekt angezeigt wird. Sobald Sie sich mit dem Swagger Petstore vertraut gemacht haben, können Sie die Spezifikation für eine andere API in den Swagger-Editor einfügen, um zu sehen, wie seine Informationen in SwaggerUI angezeigt werden.
Zusammenfassend ist Swagger Editor eine großartige Möglichkeit, sich mit dem Schreiben von API-Definitionen vertraut zu machen und wie Werkzeuge die Spezifikation analysieren, um Dokumentation zu generieren.
Weiterlesen
Für eine ausführlichere Dokumentation zum OpenAPI-Standard lesen Sie die offizielle SmartBear-Dokumentation für OpenAPI: https://swagger.io/specification/.
Sind Sie bereit, Ihre API-Dokumentation auf das nächste Level zu bringen? Buchen Sie noch heute eine Demo mit Document360!
Demo buchen
Häufig gestellte Fragen
-
Was ist eine OpenAPI?
Eine offene API (auch als öffentliche API bekannt) ist eine öffentlich verfügbare Programmierschnittstelle, die Entwicklern den Zugriff auf eine proprietäre Softwareanwendung oder einen Online-Dienst ermöglicht.
-
Was ist der Unterschied zwischen privaten und Open APIs?
Eine offene API hat Zugriffsbeschränkungen, da sie öffentlich zugänglich ist und von überall im offenen Netz aufgerufen werden kann. Eine geschlossene API, auch als private API bekannt, ist andererseits im Internet nicht öffentlich zugänglich.
-
Was ist OpenAPI und REST API?
Der OpenAPI Standard (OAS), früher als die Swagger Spezifikation bekannt, ist ein Format zur Beschreibung, Herstellung, Konsumierung und Visualisierung von RESTful Web-Diensten. Der REST API Standard beschreibt die Struktur und Syntax.