Dieser Beitrag wurde zuletzt am 12.04.2019 um 14:24 Uhr von QWERTYU bearbeitet
EinleitungNach der Nutzung asp.net Core für API-Entwicklung muss das Schreiben der API-Dokumentation für Programmierer eine mühsame Aufgabe sein, aber die Dokumentation muss geschrieben sein, und wenn es keine spezifischen Anforderungen an das Format der Dokumentation gibt, hängt die endgültige Dokumentation vollständig von der Stimmung des Entwicklers ab. Oder sei detaillierter oder einfacher. Gibt es also eine schnelle und effiziente Möglichkeit, API-Dokumentation zu erstellen? Die Antwort ist ja, Swagger ist eines der beliebtesten Tools zur Dokumentationsgenerierung von REST-APIs!
Warum Swagger als Tool zur Dokumentationsgenerierung von REST-APIs verwenden- Swagger kann eine interaktive API-Konsole generieren, mit der Entwickler schnell APIs lernen und experimentieren können.
- Swagger kann Client-SDK-Code für Implementierungen auf verschiedenen Plattformen generieren.
- Swagger-Dateien können automatisch aus Codekommentaren auf vielen verschiedenen Plattformen generiert werden.
- Swagger hat eine starke Community mit vielen starken Mitwirkenden.
Wie nutzt man Swagger, um API-Dokumentation in asp.net Kern zu generieren?- Swashbuckle.AspNetCore ist ein Open-Source-Projekt, das Swagger-Dokumentation für ASP.NET Core Web API generiert.
- NSwag ist ein weiteres Open-Source-Projekt zur Integration von Swagger UI oder ReDoc in ASP.NET Core Web APIs. Es bietet eine Möglichkeit, C#- und TypeScript-Client-Code für APIs zu generieren.
Das Folgende ist ein Beispiel für Swashbuckle.AspNetCore aufgeführtWas sind die Komponenten eines Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Stellt das SwaggerDocument-Objekt als Swagger-Objektmodell und Middleware für JSON-Endpunkte bereit.
- Swashbuckle.AspNetCore.SwaggerGen: Ein Swagger-Generator, der SwaggerDokument-Objekte direkt aus Routen, Controllern und Modellen generiert. Es wird oft mit der Swagger-Endpunkt-Middleware kombiniert, um Swagger JSON automatisch bereitzustellen.
- Swashbuckle.AspNetCore.SwaggerUI: Eine eingebettete Version des Swagger UI-Tools. Es interpretiert Swagger JSON, um anpassbare, reichhaltige Erlebnisse zu erstellen, die die Funktionalität von Web-APIs beschreiben. Es enthält integrierte Testwerkzeuge für gängige Methoden.
Wie installiert man Swashbuckle mit vs2017?
Der erste Weg: Installieren Sie über das Fenster der Paketmanager-Konsole
- Gehe zu Ansichten > anderen Windows > Paketmanager-Konsole
- Navigieren Sie zu dem Verzeichnis, das die TodoApi.csproj-Datei enthält
- Bitte führen Sie folgenden Befehl aus · Install-Package Swashbuckle.AspNetCore
-
Zweiter Weg: Aus dem Dialog "NuGet Packages verwalten":- Klicken Sie im Solution Explorer mit der rechten Maustaste auf das Projekt > NuGet-Pakete verwalten NuGet-Pakete verwalten
- Stelle Paketquelle auf nuget.org
- Gib "Swashbuckle.AspNetCore" in das Suchfeld ein
- Wählen Sie das Swashbuckle.AspNetCore-Paket im Browse-Tab aus und klicken Sie auf Installieren
-
Swagger-Middleware hinzufügen und konfigurierenFühren Sie zuerst den Namensraum ein: Füge den Swagger-Generator in der Startup.ConfigureServices-Methode zur Service-Sammlung hinzu: beiStartup.ConfigureMethode, Middleware zu ermöglichen, um das generierte JSON-Dokument und die Swagger-Benutzeroberfläche zu bedienen:
Starte die App und navigiere zu ihrhttps://localhost:<port>/swagger/v1/swagger.json。 Die resultierende Dokumentation, die den Endpunkt beschreibt, wird im JSON-Format wie folgt dargestellt.
Verfügbarhttps://localhost:<port>/SwaggerFinden Sie die Swagger-Benutzeroberfläche. Durchstöbern Sie die API-Dokumentation über die unten gezeigte Swagger-Benutzeroberfläche.
Um die Wurzel anzuwenden (http://localhost:<port>/) um die Swagger-Benutzeroberfläche bereitzustellen, bitte dieStreckenPräfixDie Eigenschaft wird auf eine leere Zeichenkette gesetzt:
Erweiterte Nutzung von Swagger (Anpassung und Erweiterungen)Verwenden Sie Swagger, um erklärende Informationen zur API-Dokumentation hinzuzufügenDie folgenden Konfigurationsoperationen werden in der AddSwaggerGen-Methode durchgeführt, die Informationen wie Autor, Lizenz und Beschreibung hinzufügt: Die Informationen zur Anzeige der Wagger-UI sind in der folgenden Abbildung dargestellt: Kommentare zu Schnittstellenmethoden hinzufügenLass uns zuerst auf die API klicken, wie in der Abbildung unten gezeigt erweitern, können es keine Kommentare geben, wie fügt man Kommentare hinzu? Fügen Sie Dokumentkommentare mit drei oder wie im untenstehenden Bild gezeigt und unten dargestellt Dann starte das Projekt und gehe zurück zur swaggerUI, um zu sehen, ob der Kommentar erscheint Ist immer noch nicht aufgetaucht, keine Sorge, schau nach unten! XML-Annotationen aktivierenSie können XML-Annotationen mit den folgenden Methoden aktivieren: - Klicken Sie mit der rechten Maustaste auf das Projekt im Lösungs-Explorer und wählen Sie Eigenschaften aus
- Schau dir das Feld XML-Dokument-Datei unter dem Ausgabebereich des Reiters Aufbau an
-
Das Aktivieren von XML-Annotationen liefert Debugging-Informationen für nicht dokumentierte gängige Typen und Mitglieder. Wenn zum Beispiel viele Warnmeldungen erscheinen, zeigt die folgende Meldung einen Verstoß gegen den Warncode 1591 an:
Was, wenn du eine Zwangsstörung hast und die Warnung aufheben möchtest? Du kannst es stornieren, wie auf dem untenstehenden Bild gezeigt
Beachten Sie den Pfad der oben generierten XML-Dokumentdatei,
Anmerkung: 1. Für Linux- oder Nicht-Windows-Betriebssysteme sind Dateinamen und Pfade groß- und schreibungssensitiv. Zum Beispiel funktioniert eine "SwaggerDemo.xml"-Datei unter Windows, aber nicht unter CentOS. 2. Um den Anwendungspfad zu erhalten, wird empfohlen, AppContext.BaseDirectory zu verwenden, um ihn zu erhalten Bauen Sie das Projekt neu auf und starten Sie, um zu sehen, ob die Kommentare erscheinen Aus der obigen Operation lässt sich zusammenfassen, dass die Swagger-Benutzeroberfläche den <summary> internen Text der Elemente des obigen Kommentarcodes als API-große Kommentare anzeigt! Natürlich können Sie auch das Element der Bemerkungen in die Anleitungsanleitung abrufen. Es kann <summary> die im Element angegebenen Informationen ergänzen und eine zuverlässigere Swagger-Benutzeroberfläche bieten. <remarks> Elementinhalte können Text, JSON oder XML enthalten. Der Code lautet wie folgt: Teste die API-Schnittstelle mit SwaggerUILassen Sie uns die Benutzeroberfläche über SwaggerUI anhand eines kleinen Beispiels debuggen
- Klicken Sie auf eine API-Oberfläche, die getestet werden muss, und klicken Sie dann auf die Schaltfläche "Try it out" links und rechts von Parameters
- Geben Sie einen Parameter in das Parametertextfeld ein, der erscheint, wie im folgenden Bild gezeigt, und geben Sie Parameter 2 ein
- Klicken Sie auf die Schaltfläche "Ausführen", und die unten gezeigte formatierte Antwort erscheint, wie in der Abbildung unten gezeigt
Nun, das war's für das heutige Tutorial zur Nutzung von Swagger zur API-Dokumentation in ASP.NET Core WebApi. Ich hoffe, es ist hilfreich für dich, zu lernen, wie man Swagger nutzt, um API-Dokumentation in ASP.NET Core zu erstellen! ZusammenfassungDieser Artikel beginnt mit dem Schmerzpunkt, API-Dokumentation manuell zu schreiben, und führt dann zu Swagger, einem Werkzeug, das automatisch API-Dokumentation generiert! Anschließend zeigen wir anhand leicht verständlicher Texte und Bilder, wie man mit SwaggerUI API-Dokumentation in einer ASP.NET Core WebAPI generiert. Abschließend werde ich einige fortgeschrittene Anwendungen von Swagger in ASP.NET Core vorstellen! Ich hoffe, es hilft dir, Swagger in ASP.NET Core zu verwenden!
| 
Veröffentlicht am 12.04.2019 14:14:46
|
|
|
|
