Vorwort
Das Team, in dem ich meine ersten Schritte auf dem Gebiet des Schreibens von Industriecode unternahm, entwickelte eine praktische API für die Funktionalität eines Softwareprodukts in C # (der Einfachheit halber nennen wir es beispielsweise den Buchstaben E), die seit vielen Jahren existiert und sich auf einer sehr positiven Seite auf dem Markt etabliert hat . Und hier sollte der junge Padawan anscheinend noch keine Fragen haben, aber stellen Sie sich vor, dass Sie früher wahrscheinlich Ihre eigenen Web-APIs geschrieben haben, aber es ist unwahrscheinlich für ein breites Publikum, was bedeutet, dass Sie nach dem Prinzip „Ich habe es selbst erstellt - Ich benutze es “, und wenn sich jemand für die Funktionalität Ihrer API interessiert hätte, hätten Sie ihm wahrscheinlich eine PDF-Datei mit detaillierten Anweisungen übergeben (zumindest hätte ich genau das getan). „Wo kann man die API-Funktionalität sehen?“ - fragte ich den Teamleiter und erwartete, einen Link zu einem Textdokument zu erhalten. „Schau dir Swagger an“, antwortete er.
Warten Sie, wie kommt es, dass das Produkt schon lange erfolgreich funktioniert und welche API Sie erst jetzt darauf schreiben?
Das ist richtig, bis vor kurzem hatte E keine bequeme öffentliche API als solche. Tatsächlich wurde die gesamte Arbeit über die Weboberfläche erledigt, und das Back-End bestand aus vielen internen Mikrodiensten, mit denen eine Integration von außen ohne ein klares Verständnis der internen Geschäftslogik unmöglich war, ganz zu schweigen von der Tatsache, dass sie selbst aus einem großen Teil des Erbes bestanden. Es war notwendig, auf Clients zu achten, die direkt mit dem Server interagieren möchten, was bedeutet, ihnen eine schöne und bequeme API zur Verfügung zu stellen. Was ist dafür erforderlich? Alles, was etwas früher geschrieben wurde, ist, die Arbeit mit allen internen Mikrodiensten selbst aufzunehmen und einzurichten sowie eine bequeme und schöne Dokumentation bereitzustellen, die es schön, verständlich und vor allem kommerziell erfolgreich macht.
Nun, was ist Swagger und was ist seine Nützlichkeit für die Welt?
Im Wesentlichen ist Swagger ein Framework für die RESTful-API-Spezifikation. Sein Reiz liegt in der Tatsache, dass es nicht nur möglich ist, die Spezifikation interaktiv anzuzeigen, sondern auch Anfragen zu senden - die sogenannte Swagger-Benutzeroberfläche, so sieht es aus:
Wie wir sehen können - eine vollständige Beschreibung der Methoden, einschließlich Modelle, Antwortcodes, Abfrageparameter - im Allgemeinen klar.
Und wie geht das?
Großartiger Leitfaden zur Implementierung von Swagger in ASP.NET Core
von Grund auf neu ist hier in
diesem Artikel.
Die Idee ist, die Anzeige mithilfe spezieller Anmerkungen für API-Methoden zu konfigurieren. Hier ein Beispiel:
Swagger Codegen
Wenn Sie wirklich möchten, können Sie direkt einen Client oder Server gemäß der Swagger-API-Spezifikation generieren. Dazu benötigen Sie einen Swagger-Codegen-Codegenerator. Die Beschreibung aus der Dokumentation muss meines Erachtens nicht erklärt werden:
Dies ist das Swagger Codegen-Projekt, mit dem API-Client-Bibliotheken (SDK-Generierung), Server-Stubs und Dokumentation automatisch mit einer OpenAPI-Spezifikation generiert werden können. Derzeit werden folgende Sprachen / Frameworks unterstützt:
- API-Clients: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 oder höher), C ++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixier, Ulme, Eiffel, Erlang, Go, Groovy, Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API-Clientbibliothek für Java, Rest-versichert), Kotlin, Lua, Node.js (ES5, ES6, AngularJS mit Anmerkungen zum Google Closure Compiler) Ziel-C, Perl, PHP, PowerShell, Python, R, Ruby, Rost (Rost, Rost-Server), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x), Typoskript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
- Server-Stubs: Ada, C # (ASP.NET Core, NancyFx), C ++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy) , Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flasche), NodeJS, Ruby (Sinatra, Rails5), Rust (Rost-Server), Scala (Finch, Lagom, Scalatra)
- Generatoren der API-Dokumentation: HTML, Confluence Wiki
- Konfigurationsdateien: Apache2
- Andere: jmeter
Weitere Informationen, insbesondere die Gebrauchsanweisung, finden Sie hier:
allgemeine InformationenUnd hier:
DetailsFazit
Dies war eine kurze visuelle Übersicht für Anfänger-API-Entwickler, deren Ziel es war, einen Überblick darüber zu geben, was Swagger ist, warum es benötigt wird und was es aus meiner persönlichen Sicht die Hauptvorteile bietet.