Teilen Sie:
){kind=small}
Lorna ist eine Software-Ingenieurin mit einer unheilbaren Blogging-Sucht. Sie versucht, Worte und Code gleichermaßen zu bändigen.
OpenAPI vereinfacht die Integration
Lesedauer: 3 Minuten
Wir nehmen unsere Entwicklerdokumentation sehr ernst, insbesondere unsere API-Referenz. Die Referenzdokumentation wird aus einer maschinenlesbaren Beschreibung jeder API generiert, in OpenAPI Format. Die Arbeit mit einem textbasierten, maschinenlesbaren Format macht die Pflege der Dokumente einfacher. Das ist schön für uns, Ihre Dokumentationsbetreuer, aber wie hilft es Ihnen, dem Benutzer? Ich bin froh, dass Sie fragen!
Werfen Sie einen Blick auf eine unserer API-Referenzseiten. Dort gibt es eine Schaltfläche mit der Aufschrift "OpenAPI 3 Spezifikation herunterladen", und wenn Sie darauf klicken, erhalten Sie das Geschenk von YAML. Sie finden alle unsere Spezifikationen auch im definitions/ Ordner unseres API Spezifikationen GitHub Repository.
Die Verwendung eines standardisierten API-Beschreibungsformats wie OpenAPI ermöglicht Ihnen den Zugang zu vielen verschiedenen Tools, die diese Dateien verstehen. Ich zeige Ihnen einige meiner Lieblingsaufgaben, die Sie mit einer OpenAPI-Spezifikation erledigen können!
Wenn man eine unbekannte API ausprobiert, kann es frustrierend sein, sich durch die Dokumentation zu wühlen, um zu verstehen, wie man eine bestimmte Anfrage zusammenstellt. Postman unterstützt den Import von OpenAPI-Spezifikationsdateien und verwandelt sie in eine vorgefertigte Sammlung von API-Anfragen. Dies ist eine hervorragende Möglichkeit, eine neue API auszuprobieren, ohne viel Zeit mit dem Lesen von Dokumentationen und dem Kopieren von Feldnamen in meinen HTTP-Client zu verbringen.
Ich bin ein großer Fan dieses Ansatzes und verwende ihn sehr häufig, sogar bei APIs, die ich so gut kenne, dass ich die curl-Befehle mit verbundenen Augen eingeben könnte. Es ist ein schneller Weg, um korrekt mit einer API zu interagieren, und ich finde ihn sehr hilfreich.
Wenn ich unterwegs bin, habe ich manchmal keine zuverlässige Internetverbindung. Wenn ich die OpenAPI-Spezifikationsdatei lokal habe (Spoiler: Ich habe die Spezifikationsdateien immer lokal, ich arbeite viel an diesem Repo!), dann kann ich eines der OpenAPI-Dokumentationstools verwenden, um Dokumente zu erstellen, die ich auf meinem Laptop verwenden kann.
Eine Möglichkeit ist die Verwendung des Tools, das wir selbst nutzen, nämlich Nexmo OAS Renderer. Es ist ein auf Ruby basierendes Open-Source-Tool, das wir selbst erstellen und veröffentlichen. Es ist zwar nicht an unsere Spezifikationen gebunden, ich verwende es hauptsächlich für unsere eigenen APIs, aber es sollte mit jeder gültigen OpenAPI v3 Spezifikationsdatei funktionieren.
Der andere Ansatz, den ich manchmal verwende, ist ein weiteres Open-Source-Tool, dieses Mal in NodeJS, namens ReDoc. Auch hier ist es nützlich, um HTML-Dokumentation aus einer OpenAPI-Spezifikation zu erstellen. Probieren Sie beide Optionen aus und wählen Sie dann Ihren Favoriten!
Die API-Beschreibung enthält Informationen über jeden Aspekt einer API. Sie enthält so viele Informationen, dass Sie diese API mit all ihren Details sehr gut imitieren könnten.
Eine sehr gute Imitation der API aus einer OpenAPI-Spezifikation ist genau das, was Prism von Stoplight bietet. Es ist ein NodeJS-Tool; installieren Sie es mit npm und starten Sie es dann lokal, und Sie haben Ihre eigene private Kopie der API aus einer OpenAPI-Spezifikation!
Ich verwende dies vor allem während der Entwicklung, wenn ich denselben API-Endpunkt viele Male aufrufe, um sicherzustellen, dass ich die verschiedenen Antworten korrekt behandle. Ein Mock-Server ist sowohl schneller als eine Remote-API und viel billiger. Außerdem gibt es keine Ratenbeschränkungen. Für jeden, der eine API integriert, sind Tools wie Mock-Server ein großer Gewinn. Für uns als API-Anbieter ist es nicht notwendig, eine Sandbox zu bauen oder zu unterstützen, damit die Leute ihre Integrationen in einem sicheren Raum entwickeln können; das ist ein Nebeneffekt der Verwendung von OpenAPI.
Ich habe drei Dinge ausgewählt, die meiner Meinung nach einen großen Unterschied für API-Benutzer machen, wenn ihr API-Anbieter OpenAPI-Spezifikationen zur Verfügung stellt. Vonage ist nicht besonders bemerkenswert bei der Veröffentlichung von API-Beschreibungen; ich würde erwarten, dass die meisten modernen API-Anbieter dasselbe tun. Hoffentlich haben Sie einige Ideen, wie Sie Ihre nächste API-Integration verbessern können. Lassen Sie uns wissen, ob Sie bereits einen dieser Ansätze verwenden oder welchen Sie als nächstes ausprobieren möchten.
Neugierig auf OpenAPI und unsere Tools? Hier finden Sie weitere Lektüre für Sie:
Die OpenAPI-Initiative: https://www.openapis.org
Der beste Ort, um nach Tools für die Verwendung mit OpenAPI zu suchen: https://openapi.tools
Postman zum Importieren einer Spezifikation, um eine Sammlung von zu verwendenden Anfragen zu erstellen: https://postman.com
Prism der Mock-Server: https://stoplight.io/open-source/prism
Weitere Vonage-spezifische Dokumente zu OpenAPI, einschließlich detaillierterer Informationen zur Verwendung von Postman und Prism sowie zur Erstellung von Dokumenten: /getting-started/concepts/openapi