👦🏻 🤱🏿 ▫️ Geben Sie es an. Yandex-Bericht 🍢 🤞🏼 🧛

Eine gute API-Spezifikation hilft Kunden bei der Verwendung. Vor einigen Monaten bei Big Pytup, Yandex-Entwickler Alexander BryazginBryazginnnmachte eine Präsentation darüber, worauf die REST-API-Spezifikation als Beispiel für OpenAPI + Swagger basiert und warum ein solches Bundle benötigt wird. In der Übersicht können Sie herausfinden, wie wir die automatische Generierung der Spezifikation im fertigen Service vermasselt haben, welche Bibliotheken für uns nützlich waren und welche Art von Optimierung sich um die OpenAPI-Spezifikation handelt.

- Hallo zusammen, ich heiße Alexander. Ich möchte mit Ihnen über die Spezifikationen sprechen.

Insbesondere möchte ich auf einige Themen eingehen. Was sind Spezifikationen am Beispiel der REST-API-Spezifikationen? Weiter - als wir die Generierung der Spezifikation in unserem Service befestigten. Und am Ende auf der süßen Seite - welche Tools, Tuning, um die Ergebnisse unserer Spezifikationsgenerierung zu verwenden, am Beispiel einer Spezifikation wie OpenAPI und Swagger UI.

REST-API-Spezifikation

Was sind Spezifikationen und was meine ich damit in meinem Bericht?

Zuallererst ist es die Schnittstellenbeschreibungssprache, eine Sprache zur Beschreibung von Schnittstellen, eine Beschreibung, die einem bestimmten Format entspricht. Es kann automatisch analysiert werden, da es ein striktes Format und solche Besonderheiten hat, dass es nicht von der Sprache selbst abhängt, in der die Schnittstelle implementiert ist. Angenommen, Sie haben einen Python-Webserver, für die Sprache der Schnittstellenbeschreibung spielt dies keine Rolle.

Es gibt viele Sprachen zum Spezifizieren von Spezifikationen. Dies sind Spezifikationen für REST, RPC, GraphQL usw. Heute werden wir uns mit der REST-Spezifikation befassen.

Openapi

Lassen Sie uns anhand des OpenAPI-Beispiels über Spezifikationen sprechen.

Lassen Sie uns zunächst verstehen, was OpenAPI ist. Dies ist genau die gleiche Sprache, um die Spezifikationen zu beschreiben. An sich ist es eine Datei - im Format YAML, JSON oder XML, wer es mehr mag - mit einer Beschreibung der Schnittstelle, der Handle-Endpunkte und der Schemata.

Stolzieren

Wenn wir über OpenAPI sprechen, können wir nichts über Swagger sagen.

Swagger ist im Wesentlichen eine OpenAPI-Benutzeroberfläche, mit der Sie Ihre Spezifikation wunderschön visualisieren können.

In Swagger wie in OpenAPI gibt es eine Beschreibung der Endpunkte, die in Ihrer Spezifikation enthalten sind.

In Ihrer API befindet sich eine Beschreibung der Autorisierung.

Es gibt eine Beschreibung der Modelle oder Schaltkreise, mit denen Sie in Ihrer API arbeiten. Akzeptieren Sie sie beispielsweise zur Eingabe oder geben Sie sie zur Ausgabe zurück.

Es gibt eine Beschreibung von Beispielen und erwarteten Anforderungen und Antworten von Ihrer API.

Darüber hinaus können Sie in Ihrem Swagger aufgrund der Tatsache, dass es sich um eine Benutzeroberfläche handelt und in Ihrem Browser ausgeführt wird, hier und jetzt in Echtzeit Anforderungen an Ihre API ausführen.

^{_{Link von der Folie}}

Mit all dem können Sie auf einem vom Swagger-Team vorbereiteten Prüfstand herumspielen. Dies ist petstore.swagger.io. Es gibt eine Beispielspezifikation, die von Swagger angesprochen wurde. Sie können zum echten Backend gehen und berühren. Empfehlen.

Also sagen wir: OpenAPI, Swagger, Spezifikation. Aber warum wird all dies für eine Person benötigt, die beispielsweise ein Backend schreibt?

Erstens werden Spezifikationen häufig während der Entwurfsphase unserer API verwendet. Das heißt, normale Leute, die sich der Aufgabe gestellt haben, ein Backend zu schreiben, beschreiben zunächst, was sie implementieren möchten. Das heißt, sie beginnen mit dem Entwurf ihrer API, einer Liste der Endpunkte, die sie implementieren möchten, einer Liste der zu manipulierenden Schemata, Parameter usw. In diesem Fall sind die Spezifikationen und Tools rund um die Spezifikationen sehr praktisch.

Darüber hinaus gibt es einen beliebten Fall. Für das, was wir die Spezifikation im Dienst zu uns gezogen haben? Dies ist die Dokumentation. Die Verfügbarkeit von Spezifikationen bietet Ihnen eine gute Gelegenheit, Ihre API zu beschreiben und diese Informationen mit jemandem zu teilen: entweder mit den Front-End-Anbietern in Ihrem Team oder mit externen Kunden, die sich in Sie integrieren möchten.

Aufgrund der Tatsache, dass die Spezifikation in einem bestimmten strengen Format geschrieben ist, kann sie auch automatisch verarbeitet werden, dh an der Selbstbeobachtung der API beteiligt sein. Und obendrein können Sie viele Werkzeuge fangen, die Ihnen das Leben erleichtern können. Ich werde es Ihnen später genauer und ausführlicher erläutern.

Wie wir OpenAPI vorbereiten

Wir haben uns entschieden, warum wir das alles brauchen. Lassen Sie uns darüber sprechen, wie wir die Erstellung von Spezifikationen in unserem Service vermasselt haben. Zunächst ein kleiner Kontext.

Als wir zu dem Schluss kamen, dass wir die Spezifikation kürzen würden, folgten wir nicht dem normalen Pfad, als wir das Projekt zum ersten Mal im Sinne eines Prototyps mit einer Spezifikation schrieben. Wir haben bereits ein Backend erstellt, es flog bereits mit uns und wir wollten die Spezifikation als Dokumentationsmethode teilen.

Und unser Backend war plötzlich in Python. Wir haben Falcon als Framework, Marshmallow als Serialisierungs- und Deserialisierungswerkzeug und Webargs als Validierungswerkzeug verwendet.

Mit dem einfachsten Ausschnitt aus dem Petstore, den ich zuvor erwähnt habe, können wir uns vorstellen, wie unser Service in der Phase aussehen könnte, in der wir eine Spezifikation erstellen wollten.

In unserem Dienst würde es ein vereinfachtes Paar von Schemata geben: den Typ unseres Haustieres, dh die Kategorie, und tatsächlich die Tiere selbst.

Das heißt, wir würden mehrere Schemata auf Marshmallow beschreiben. Außerdem würden wir einige Stifte vorbereiten, um beispielsweise unsere Favoriten zu registrieren und zu erhalten.

Tatsächlich würden sie die Anwendung selbst beschreiben, was den Endpunkt für das Erstellen und Empfangen von Haustieren erhöhen würde.

So würde es zusammen aussehen. Ziemlich einfacher Service.

Lassen Sie uns darüber nachdenken, welche Optionen wir zum Erstellen einer OpenAPI-Konfiguration haben. Die einfachste und naivste Option ist, wie ich bereits sagte, nur eine Datei. Warum machen wir diese Datei nicht mit unseren Händen? Wir wissen, welche Eingabedaten wir haben, wir haben Endpunkte. Es scheint offensichtlich, nehmen Sie einfach und schreiben Sie.

Vor allem aber sind wir Programmierer. Wir machen nichts gerne mit unseren Händen. Wir möchten, dass etwas Standard für uns generiert wird. Zweitens, wenn wir alles von Hand unterstützen würden, müssten wir sicherlich API-Änderungen sowie eine Datei unterstützen, die woanders liegt. Wie jeder Service ist auch unser Produkt volatil, ebenso wie die Spezifikation.

Daher sind wir zu dem Schluss gekommen, dass wir eine OpenAPI-Konfiguration generieren wollen. Angesichts unseres Technologie-Stacks haben wir eine Bibliothek wie apispec gefunden . Apispec ist eine Bibliothek von Herstellern, dh den Autoren von Marshmallow und Webargs. Zusammen bilden sie ein großes Ökosystem.

Mal sehen, wie Sie Apispec auf unserem Stack verwenden können, um zu lernen, wie eine Spezifikation für uns generiert wird.

Wir hatten eine Ressource und einen speziellen Handler für die get-Methode dieser Ressource. Er hat eine Art Körper.

Um Apispec zu lehren und ihn wissen zu lassen, was wir in unserem Stift tun, fügen wir dem Dokument etwas hinzu. Wir fügen dort eine Beschreibung hinzu, die für den Menschen verständlich ist. In unserem Fall ist dies ein Beispiel für Antworten: Manchmal kommt es vor, dass unser Stift mit zweihundert antwortet, und im Hauptteil unserer Antwort befindet sich JSON mit einem Schema, dem Pet-Datenmodell.

Am Beispiel einer Nachanfrage beschreiben wir: Zusätzlich zu der Tatsache, dass es eine Antwort 201 gibt, in der wir Pet zurückgeben, gibt es auch den erwarteten Text der Anfrage, der zu uns kommt. Und innerhalb dieser Anfrage erwarten wir JSON und erwarten, dass dieser JSON im Pet-Format vorliegt.

Wir haben docstrings hinzugefügt, dann müssen wir lernen, wie man eine Spezifikation generiert. Dazu schreiben wir eine Art Skript, einen roten Knopf, und bringen apispec bei, eine Spezifikation für uns zu generieren. Wir deklarieren ein Apispec-Objekt, aus dem wir einige Metadaten unseres Dienstes beschreiben, und schreiben dann einfach die Datei, die generierte Spezifikation, im YAML-Format.

Mal sehen, was für diese riesige Anwendung in dieser Datei generiert wurde.

Zunächst enthält diese Datei eine Beschreibung der Version, in der die Spezifikation generiert wurde. Dies ist wichtig, damit jeder, der diese Spezifikation interpretiert, versteht, welches Format zu interpretieren ist. Die technischen Daten variieren von Version zu Version.

Weiter gibt es eine Beschreibung unseres Service. Dieser Titel, die Version, vielleicht gibt es eine Beschreibung, wenn Sie es wollen, und dann eine Liste von Servern, zu denen Sie gehen, die Stifte ziehen, unser Backend sehen und berühren können.

Darüber hinaus sprießen die Datenschemata selbst, die wir dort manipulieren, mit einer Beschreibung der Typen, Beispielen zum Ausfüllen dieser Daten und einigen Regeln. Vielleicht sind dies einige Extremwerte, vielleicht die Bindungsparameter. Hier sehen Sie eine Liste der erforderlichen Attribute.

Zusätzlich zu den Schemata wächst dort die Beschreibung der Endpunkte. In diesem Fall sprießt die Beschreibung jeder Methode.

Mit der get-Methode erhalten wir eine Beschreibung dessen, was wir mit der get-Methode machen.

Und genau die Beschreibung, die wir in die Dokumentzeichenfolgen des entsprechenden Endpunkts eingefügt haben, ist auf dem Post entstanden. Das heißt, wir haben bereits eine Art Datei erhalten.

Was sollen wir jetzt damit machen? Was nützt das? Zunächst einmal können Sie als Eigentümer des Backends bereits all diesen potenziellen Kunden, die zu Ihren Stiften gehen, diese Spezifikation geben. Und das wird den Jungs helfen, sich zu integrieren. Das heißt, die Datei, die wir erstellt haben, lässt Sie nicht die Augen ausstechen. Es ist gut lesbar. Es kann durch die Augen gesehen und irgendwie analysiert werden.

Das ist aber auch schwierig. Mal sehen, welche anderen Tools es gibt, um Ihr Leben zu vereinfachen, und welche Art von Abstimmung sich um die generierte Spezifikation dreht.

Gebäck

Und dann kommen wir zur nächsten Phase, in der wir anhand des OpenAPI-Beispiels über ein nützliches Toolkit für Spezifikationen sprechen.

^{_{Link von der Folie}}

Das erste Tool, über das ich sprechen möchte, ist Swagger-UI. Im Folgenden werde ich Links zu einer Webressource bereitstellen, in der Sie das entsprechende Tool, in diesem Fall SwaggerHub, oder den Befehl zum Starten des entsprechenden Dokuments mit Docker aufrufen können.

Wir alle lieben Docker sehr. Docker hilft Ihnen dabei, JavaScript oder Java nicht lokal zu installieren. Nehmen Sie es einfach, führen Sie es mit einem Befehl aus, und alles funktioniert für Sie.

Swagger-UI ist also in der Tat ein Dienstprogramm, mit dem Sie Ihre Spezifikation wunderschön anzeigen können. Wie ich bereits sagte, werden diese lokal mit Docker ausgeführt, möglicherweise mit Swagger.

Sie können das Gebietsschema anzeigen oder freigeben, indem Sie die Spezifikation in Swagger auf Ihrer Hardware ausführen. Senden Sie außerdem alle potenziellen Benutzer an diese Spezifikation. Sie ist schon viel verständlicher, schöner. Direkt darin können Sie die Abfrageausführung durchführen.

^{_{Link von der Folie}}

Zusätzlich zur Swagger-Benutzeroberfläche gibt es ein praktisches Swagger-Editor-Tool. Sie können es im Web verwenden, Sie können es in einem Gebietsschema oder auf einer beliebigen Schreibmaschine abrufen. Sie können die Spezifikation in Echtzeit ändern und ihre Anzeige hier sehen. Das heißt, es ist ein sehr praktisches Tool zum Beispiel beim Entwerfen einer API, wenn Sie keine Spezifikation generiert haben und Ihr Backend irgendwie streicheln oder beschreiben möchten, ohne ein reales oder generiertes Backend hinter sich zu haben.

Als nächstes kommt das wunderbare Prisma-Tool. Ich möchte näher darauf eingehen. Prism ist ein Dienstprogramm von Spotlight. Mit der Spezifikation können Sie den Mock-Server anheben, der gemäß der Spezifikation funktioniert, die Sie ihm zugeführt haben.

Das heißt, in diesem Fall sehen wir die Einführung von Prism über der Spezifikation, die ich direkt unter dem Swagger-Laden gestohlen habe. Wir sehen, dass Prism alle Endpunkte gefunden hat, die in der Spezifikation angegeben sind, und gesagt hat, dass sie sie ehrlich stören.

Versuchen wir zu fühlen, was Prism kann.

Zuerst finden wir den Stift, versuchen ihn zu ziehen und plötzlich sehen wir, dass Prism uns sagt: Entschuldigung, 401 Fehler. Wir gehen in die Spezifikation und sehen, dass dieser Stift tatsächlich hinter der Autorisierung verborgen ist. Der Sicherheitsbereich ist dort klar beschrieben. Darin sehen wir, dass die Autorisierungsmethode OAuth ist, und wir verstehen: Tatsächlich hat Prism eine Art Autorisierungsdaten von uns erwartet.

Versuchen wir, ihm Autorisierungsdaten in dem Format zu übertragen, auf das er wartet. Es ist klar, dass das Zeichen irgendwie luftig ist, für Prisma spielt es keine Rolle, was es im Wesentlichen ist. Das Format ist ihm wichtig. Das heißt, wenn er auf OAuth wartet, wartet er auf Autorisierungsdaten in einem bestimmten Format.

Wir ruckeln mit der Autorisierung und sehen bereits den 400. Fehler. Wir schauen uns an, was wir in der Spezifikation haben. In der Spezifikation sehen wir, dass wir einige erforderliche Attribute nicht übergeben haben. Lassen Sie uns sie weitergeben.

Das magische Attribut ist Status. Es wird in der Tat gemäß der ENUM-Spezifikation angegeben. Wenn wir einen Status übertragen hätten, der nicht in dieser ENUM enthalten ist, hätten wir einen Vierpunkt.

Hier haben wir den gültigen Status übergeben und sehen, dass das Backend mit einer vollständig gültigen XML mit den Daten geantwortet hat. Die Daten in dieser XML werden jetzt nur noch aus dem in der Spezifikation angegebenen Beispiel zurückgegeben. Das heißt, in der Spezifikation für jedes Feld gibt es einen solchen Abschnitt als Beispiel, in dem Sie ein Beispiel für Daten angeben können, die zurückgegeben werden können. Hier brachte Prisma sie gerade zurück.

Aber abgesehen von der Tatsache, dass Sie den Stift ziehen können und erwarten, dass es ehrliche zweihundert geben wird, gibt es die Möglichkeit, Prisma zu sagen - geben Sie mir einen bestimmten Antwortcode zurück. Normalerweise beschreiben wir in der Spezifikation das unterschiedliche Verhalten unseres Stifts, und mit gültigen Daten entsprechen sie nicht immer zweihundert. Sie können beispielsweise nach IDs in der Datenbank suchen, um festzustellen, dass eine solche ID nicht vorhanden ist.

In diesem Fall deklarieren wir jedem einen bestimmten Code, beispielsweise den 400. oder 422., wie Sie möchten. Das heißt, mit einem gültigen Eintrag gibt es nicht immer einen gültigen Ausgang. Daher beschreiben wir in der Spezifikation verschiedene Antwortoptionen. Und wir können beim Ruckeln des Stiftprismas klar sagen: Dieses Mal warte ich darauf, dass Sie mir antworten, sagen wir, der 404. Fehler. Angenommen, dies ist ein Fall, wenn ich mit einer ID am Griff ziehe, aber es gibt keine solche ID.

Zusammenfassend: Welche Funktionen gibt es im Allgemeinen zusätzlich zu den bereits erwähnten? Auch dies ist ein Mock-Server, den Sie abholen können. Er wird gemäß der Spezifikation antworten und Autorisierungsanfragen validieren. Es werden auch die Daten überprüft, die Sie an das Gerät gesendet haben.

Zusätzlich zur Validierung der Anforderung werden Antworten generiert. Im einfachsten Fall werden, wie gesagt, Antworten anhand von Beispielen generiert. Es gibt eine zweite Option - wenn Sie explizit danach fragen: Bitte generieren Sie dynamische Antworten. Eine dynamische Strategie bedeutet, dass je nach Typ, z. B. int, Tausende, Milliarden oder etwas anderes generiert werden. Oder für die Zeichenfolge ein seltsamer und unverständlicher Hash.

Als ich beim ersten Durchlauf sagte, dass Sie Daten generieren können, fragten wir uns: Es wäre cool, wenn Prism in faker integriert wäre. Diejenigen, die den Python-Fälscher verwendet haben, wissen wahrscheinlich, wie cool es ist, wenn Sie einige Daten sperren oder Daten in der Datenbank emulieren möchten.

Prism ist also in JavaScript geschrieben. JavaScript hat auch Faker.js und Prism hat eine automatische Integration mit faker. Sie können in Ihrer Spezifikation explizit angeben, welche Arten von Fälschungsdaten Ihr Stift geben soll. Das heißt, OpenAPI unterstützt ein Plug-In-System, mit dem Sie Ihre Spezifikation erweitern können, sodass OpenAPI und der Parser selbst keine Rolle spielen. Wenn es jedoch Plugins gibt, die Ihre Spezifikation analysieren, können sie einige zusätzliche Felder verwenden.

Prism bietet Ihnen daher die Möglichkeit, das optionale X-Faker-Plugin-Feld zu verwenden. Sehr bequem.

Hier habe ich unter dem Sternchen angegeben, dass Rückrufe in OpenAPI beschrieben werden können. Dies ist das Interaktionsschema, wenn Sie einen Rückruf an einen bestimmten Stift registrieren und darauf warten, dass Sie einen bestimmten Rückruf an die von Ihnen registrierte URL erhalten. Also, Prisma und es weiß, wie man nass wird.

Interessant: Prisma kann nicht nur im Mock-Modus, sondern auch im Proxy-Modus angehoben werden. Sie stellen diesen Proxy einfach vor Ihr echtes Backend, und alle Anforderungen, die Prism durchlaufen und zurückkommen, werden von Prism gemäß den Spezifikationen validiert.

Wenn einige Daten - z. B. Eingabe oder Ausgabe, Anforderung oder Antwort - voneinander abweichen, schreibt er dies in das Protokoll. Er macht das ganz transparent, es hat keinen Einfluss auf das wirkliche Verhalten. Im Allgemeinen heißt es in der Dokumentation, dass es in der Produktion leicht angehoben werden kann. Ehrlich gesagt habe ich es nicht selbst versucht. Sicher gibt es eine Art Overhead, aber ich kann immer noch nichts dazu sagen. Sie können fühlen, versuchen und erzählen.

Darüber hinaus ist es durch das, was ich bereits gesagt habe, möglich, bestimmte Anfragen zu erzwingen. Das heißt, kommen Sie zum Mock-Server und sagen Sie: Ich möchte ein bestimmtes Beispiel oder eine bestimmte Art von Antwort. Wir haben bereits über die Art der Antwort gesprochen. Auch in der OpenAPI-Spezifikation können mehrere Antwortoptionen angegeben und explizit benannt werden.

Sie können also kommen und Prisma sagen: Dieses Mal möchte ich ein bestimmtes Beispiel, das nächste Mal möchte ich ein anderes Beispiel.

^{_{Link von der Folie}}

Über Prisma gesprochen. Nun zum Postboten. Ich liebe ihn so sehr. Postman ist also sofort in OpenAPI integriert. Sie können die OpenAPI-Spezifikation buchstäblich mit nur zwei Tastenklicks importieren. Und er erstellt eine Sammlung von Anfragen gemäß Ihrer Spezifikation.

Gleichzeitig bereitet er alle Abfrageparameter, alle Körperparameter, alle Umgebungen und Berechtigungen vor. Sie müssen die Daten nur mit einigen echten IDs oder etwas anderem, Autorisierungstoken, beenden. Sehr bequem.

Wir fahren vom Postboten weiter. Wir haben über Prism gesprochen, es hat Funktionalität - Abfragevalidierung. Tatsächlich gibt es ein separates Dienstprogramm, mit dem Sie Ihr wirklich laufendes Backend gnadenlos saugen und sehen können, ob es wirklich gemäß der Spezifikation funktioniert.

Dredd analysiert die Spezifikation. Er nimmt, zieht alle Stifte und schaut auf das, was zu ihm zurückgekehrt ist. Im Allgemeinen kann dredd als Infrastruktur zum Schreiben von Tests behandelt werden, da alle seine Anforderungen durch seine Hooks ergänzt werden können. Das heißt, von der Box aus können Sie dredd so starten, wie es ist, wie ich es hier gestartet habe.

Oder Sie können dredd ausführen, indem Sie eine Reihe von Hooks übergeben, die tatsächlich in der Ideologie eines regulären Tests funktionieren. Es gibt etwas, das sich auf die gesamte Testreihe auswirkt. Es gibt Hooks, die vor dem Test, nach dem Test und der gesamten Infrastruktur ausgeführt werden.

^{_{Link von der Folie}}

Als nächstes möchte ich detaillierter auf ein solches Tool von Swagger selbst als Swagger-Codegen eingehen. In der Tat ist es ein bisschen wie ein Schweizer Messer. Was für Gedanken hatten die Jungs, als sie dieses Instrument geschrieben haben.

Wenn jemand in ein Backend integriert werden muss, beschreiben Sie normalerweise selten eine http-Anfrage hier zu einem bestimmten Zeitpunkt in der Geschäftslogik. Am häufigsten kapseln Sie die Arbeit mit einem bestimmten Backend in einer Entität im Client.

Die Jungs kamen also auf die Idee, dass wir mit einer Spezifikation ganz klar beschreiben und vorhersagen können, wie der Client für dieses Backend aussehen würde. Und die Jungs haben einen Kundengenerator gemacht.

Versuchen wir, die Client-Generierung gemäß der Petstore-Spezifikation zu starten. Wir werden sehen, dass dieser Generator vom Swagger-Client selbst generiert wurde, in dem sich der Python-Client selbst befindet. Hier in der Startzeile können Sie deutlich sehen, dass ich einen Client in Python generiere. Tatsächlich unterstützt es eine große Anzahl von Sprachen. Was ist hier wichtig? Spitzenreiter werden JavaScript mögen, Hipster werden Go mögen. Alles was du willst.

Zusätzlich zum Client in Python erstellte er einige Dokumente und testete magische Ordner. Wir werden später ausführlicher darüber sprechen. Und viel Zucker, damit Sie diesen Client in eine fertige Bibliothek einwickeln können. Es gibt Gitignore, es gibt CI-Dateien, sagen wir für Travis, es gibt Zucker für Git. Es gibt Anforderungen, setup.py und tox.ini. Das heißt, alles, was Ihnen hilft, diesen Client einfach zu übernehmen, festzuschreiben und zu senden, liegt bereits in Form einer Bibliothek vor, die wiederverwendet werden kann.

Schauen wir uns genauer an, was er im Client generiert hat.

Im Client generierte er neben einigen Hilfsdateien zwei sehr wichtige Verzeichnisse API und Modelle. In Modellen haben wir die Datenmodelle, die wir manipulieren. Jedes Modell ist einfach eine Python-Klasse, die von einem Objekt mit __init__ geerbt wird, das alle Arten von Parametern für dieses Schema verwendet, sowie Getter und Setter, die den Status des Objekts ändern.

Neben dem Modell wurden dort auch Entitäten wie PetApi angezeigt. Dies sind lediglich Client-Wrapper über der Endpunktgruppe, die OpenAPI entweder nach Tags oder nach Endpunkten gruppiert.

Und dieser Client verfügt über alle Stifte, die Sie zucken können, um echte Daten zu übertragen. Dann fliegen sie zu einem Backend.

Was wird von diesem generierten Client implementiert? Aus dem Interessanten - dem vertraglichen Ansatz. Reden wir mehr über ihn.

Der vertragliche Programmieransatz legt nahe, dass Sie bei der Implementierung der Interaktion zwischen Client und Server immer bestimmte Regeln und Verträge einhalten, unabhängig davon, ob es sich um Daten handelt, die der Client an den Server weitergibt, oder um Daten, die der Server an den Client weitergibt.

Der Vertragsansatz empfiehlt Ihnen daher, Ihre Daten und Ihre Interaktion jedes Mal in Echtzeit auf Einhaltung des Vertrags zu überprüfen. Wenn dieser Vertrag ein Schema der von uns übermittelten Daten ist und nicht unseren Erwartungen entspricht, nicht erfüllt ist, müssen Sie dies sagen und den Fehler hier und jetzt anzeigen. Gehen Sie nicht zum echten Backend, warten Sie nicht auf vier Punkte, sondern sagen Sie es jetzt.

Oder ein anderer Fall: Wir sind zum Backend gegangen, haben einige Daten erhalten, aber sie entsprechen nicht dem, worauf wir gewartet haben. Angenommen, einige Felder, von denen wir erwartet haben, dass sie gefüllt sind, werden leer. Wir werden hier und jetzt darüber sprechen und nicht, wenn wir irgendwo im Wald irgendwo auf dem Call-Stack liegen und nicht herausfinden, warum etwas heruntergefallen ist.

Swagger-Codegen generiert also Kunden und Modelle gemäß dem Vertragsansatz. Sie können in Echtzeit sagen: Ja, ich möchte, dass der Client zur Laufzeit alle Daten auf Einhaltung der Verträge überprüft. Und wenn der Vertrag nicht erfüllt ist, wird er dies sofort sagen.

Wir haben eine Art Pit-Client mit einem vertraglichen Ansatz generiert, aber außerdem hat Swagger-Codegen Dokumentations-Stubs für uns generiert. Tatsächlich sind sie recht einfach, aber sie können alle für jedes Modell gedreht werden.

Auch Swagger-Codegen erzeugte eine Art Teststubs. Alles, damit Sie den generierten Code mit minimalem Aufwand ausrollen und mit Tests mit kontinuierlicher Integration in Form einer Bibliothek mit einem Git mit allen Schnickschnack ausführen können.

Lassen Sie uns noch einmal kurz darauf eingehen. Wir haben uns nur einen Fall angesehen - eine Möglichkeit, Clients für die API zu generieren. Aus dem wichtigen vertraglichen Ansatz. Ich möchte sagen: Als ich einen Kunden für eine echte Zoohandlung gemäß deren Spezifikationen generiert habe und wirklich zu deren Backend gegangen bin, hat dieser vertragliche Ansatz plötzlich die ungültigen Daten erfasst, die von der Zoohandlung zurückgegeben wurden.

Zuerst dachte ich - sie sind ein bisschen seltsam. Sie selbst haben die Spezifikation generiert, und das Backend funktioniert für sie nicht richtig. Aber es scheint mir, dass sie es absichtlich getan haben, damit wir die Kraft des Vertragsansatzes sehen können. Es gab nicht viele Daten und sie wurden eindeutig generiert.

Auch in der Kundengeneration und in einer anderen Generation können Sie Ihre eigenen Vorlagen verwenden. Wenn Sie also einen Client in einem bestimmten Format generieren möchten, können Sie Ihre Vorlage speichern und vorbereiten und Clients nach Ihren Wünschen generieren. Wenn Sie jeden Tag herumgehen und Integrationen generieren, wird es Ihnen vielleicht sehr gefallen.

Sie können diese Clients auch konfigurieren und den Import Ihrer Modelle schreiben, anstatt der von Swagger-Codegen generierten.

Zusätzlich zum Generieren von Clients für die API können Sie die Spezifikation dem Generator zuführen und die Stubs des Servers selbst generieren. Das ist sehr merkwürdig. Das heißt, Sie generieren eine Art Backend, das angeblich gemäß der Spezifikation funktioniert. Es ist klar, dass es dort keine Geschäftslogik gibt. Aber vielleicht ist es praktisch als eine Art Gerüst, das heißt, einen Entwurf vorzubereiten, mit dem Sie bereits etwas tun können. Ich habe es nicht benutzt, aber ich empfehle einen Blick darauf zu werfen - vielleicht finden Sie etwas Nützliches für sich.

Unter anderem können Sie Dokumentation im HTML- und Confluence-Format erstellen, wenn jemand sie verwendet. Dort endeten auch die Beispiele, die ich für OpenAPI zeigen wollte.

^{_{Alle diese Tools sind unter den beiden folgenden Links auf der Folie verfügbar : openapi.tools undgithub.com/APIs-guru/awesome-openapi3}}

Ich möchte die Tuning-Gruppen in der OpenAPI-Spezifikation anzeigen. In der Tat gibt es viele Werkzeuge. Dies sind nur Gruppen, dh Arten von Werkzeugen, die Sie verwenden können.

Von Bedeutung ist hier ein Konverter von einer Spezifikation zur anderen. Das heißt, Sie können die Blueprint-API oder was auch immer Sie möchten aus der OpenAPI-Spezifikation generieren und umgekehrt. Es gibt eine Bibliothek für Mock, für Dokumentation. Das heißt, alles, worüber ich gesprochen habe, wird sich in diesen Gruppen widerspiegeln.

Es gibt einen Link, dem Sie auch folgen können. Achten Sie darauf, schauen.

^{_{Link von der Folie}}

Neben den Tools rund um OpenAPI gibt es auch Tools rund um Swagger. Es gibt SwaggerHub und Swagger Inspector. Sie werden blau hervorgehoben, da es sich um ein webbasiertes Toolkit handelt. Sie können direkt dorthin gehen und als Dienst den SwaggerHub und den Swagger Inspector verwenden, die eigentlich eine Überlagerung der folgenden Bibliotheken darstellen: Swagger-Editor, Swagger-Codegen, Swagger-UI. All das haben wir gerade besprochen.

Alle Bibliotheken sind gelb, wie wir gesehen haben, Open Source. Es gibt auf GitHub, in Form von Docker. Verwenden.

Fazit

Was haben wir heute besprochen? REST-API-Spezifikation am Beispiel von OpenAPI und Swagger. Ich möchte betonen, dass OpenAPI nur eine Möglichkeit ist, die Spezifikation zu beschreiben. Es gibt viele davon. Siehe auch die Blueprint-API. Vielleicht mag jemand anderes etwas.

Wir haben auch Swagger gesehen. Im Wesentlichen handelt es sich, wie bereits erwähnt, nur um eine schöne Benutzeroberfläche rund um die Spezifikation, mit der Sie sie auf bequeme Weise anzeigen und erkunden können. Tatsächlich gibt es auch viele dieser Tools, die von ReDoc und Sphinx bis hin zu Markdown reichen. Das heißt, Sie können Markdown aus OpenAPI generieren und es wird in allen GitHub, GitLab - wo immer Sie wollen - wunderschön angezeigt.

Wir haben uns auch ein Beispiel auf unserem Technologie-Stack angesehen, wie wir jetzt die Spezifikation generieren. Aber wie Sie bemerkt haben, ist dies ziemlich kompliziert und unpraktisch, da wir tatsächlich Geschäftslogik und Dokumentstrings duplizieren.

^{_{Links von der Folie: FastAPI , SAFRS , rororo}}

Von Interesse empfehle ich Ihnen, sich FastAPI anzuschauen. Styopa wird Ihnen heute mehr darüber erzählen . Mit FastAPI können Sie sofort eine Spezifikation erstellen. Ihnen fällt dort überhaupt nichts ein. Schreiben Sie einfach den Code und erhalten Sie die fertige Spezifikation.

Es gibt zwei weitere Frameworks: SAFRS und Rororo. Die Namen sind natürlich magisch. Sie arbeiten ein wenig an einem anderen Modell, lassen Sie nicht über die Spezifikation nachdenken und bekommen sie nur als Nebeneffekt. Im Gegenteil, Sie haben eine Spezifikation, die Handler antreibt. Dies ist grob gesagt eine spezifikationsgetriebene Entwicklung. Sie haben nicht so viele Sterne wie FastAPI, aber es scheint mir, dass sie Aufmerksamkeit verdienen, werfen Sie einen Blick darauf.

Und schließlich haben wir anhand der Beispiele von OpenAPI und Swagger besprochen, welche Art von Dienstprogramm es um die Spezifikation gibt. Für alle Punkte, die ich

verlinke , gibt es sicher viele interessante Dinge: - OpenAPI / Swagger
swagger.io/docs/specification/about

- Beispiel für Falcon + Marshmallow + Apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- OpenAPI / Swagger
Brötchen
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

Was habe ich ? war die Nachricht des Berichts? Leute, das Schreiben von Spezifikationen ist keine Bürokratie. Und das ist nicht so schwierig, wie es auf den ersten Blick erscheinen mag, sondern eher einfach und bietet viele nützliche Werkzeuge, die Ihnen große Chancen eröffnen.

Schreiben Sie die Spezifikationen. Empfehlen. Vielen Dank.

Alle Codes und Links sind in der Präsentation verfügbar .