Verwendung von Swagger in ASP.Net Core

Oft möchten Sie eine Dokumentation für Ihre API erstellen. Um diese Dokumentation zu erstellen, können Sie Swagger nutzen - ein Tool, mit dem Sie auf einfache Weise eine UI-Darstellung Ihrer API bereitstellen können. Nachdem Sie die Swagger-Dokumentation für Ihre API erstellt haben, können Sie die Signatur Ihrer API-Methoden anzeigen und sogar Ihre API-Methoden testen.

Swashbuckle ist ein Open Source-Projekt zum Generieren von Swagger-Dokumenten. Dieser Artikel enthält eine Diskussion darüber, wie wir Swashbuckle nutzen können, um interaktive Dokumentation für unsere RESTful-API zu generieren.

Erstellen Sie ein ASP.Net Core-Projekt

Zunächst erstellen wir ein ASP.Net Core-Projekt in Visual Studio. Angenommen, Visual Studio 2017 oder Visual Studio 2019 ist auf Ihrem System installiert, führen Sie die folgenden Schritte aus, um ein neues ASP.Net Core-Projekt in Visual Studio zu erstellen.

  1. Starten Sie die Visual Studio-IDE.
  2. Klicken Sie auf "Neues Projekt erstellen".
  3. Wählen Sie im Fenster "Neues Projekt erstellen" aus der Liste der angezeigten Vorlagen "ASP.Net Core-Webanwendung" aus.
  4. Weiter klicken. 
  5. Geben Sie im nächsten Fenster "Konfigurieren Sie Ihr neues Projekt" den Namen und den Speicherort für das neue Projekt an.
  6. Klicken Sie auf Erstellen. 
  7. Wählen Sie im Fenster "Neue ASP.Net Core-Webanwendung erstellen" .Net Core als Laufzeit und ASP.Net Core 2.2 (oder höher) aus der Dropdown-Liste oben aus.
  8. Wählen Sie "API" als Projektvorlage aus, um ein neues ASP.Net Core Web API-Projekt zu erstellen. 
  9. Stellen Sie sicher, dass die Kontrollkästchen "Docker-Unterstützung aktivieren" und "Für HTTPS konfigurieren" deaktiviert sind, da diese Funktionen hier nicht verwendet werden.
  10. Stellen Sie sicher, dass die Authentifizierung auf "Keine Authentifizierung" eingestellt ist, da wir auch keine Authentifizierung verwenden.
  11. Klicken Sie auf Erstellen.

Wenn Sie diese Schritte ausführen, wird in Visual Studio ein neues ASP.Net Core-Projekt erstellt. Wir werden dieses Projekt in den folgenden Abschnitten dieses Artikels verwenden, um zu untersuchen, wie wir eine Swagger-Dokumentation für den ValuesController generieren können.

Installieren Sie die Swagger-Middleware in ASP.Net Core

Wenn Sie ein ASP.Net Core-Projekt erfolgreich erstellt haben, sollten Sie als Nächstes die erforderlichen NuGet-Pakete zu Ihrem Projekt hinzufügen. Wählen Sie dazu das Projekt im Projektmappen-Explorer aus, klicken Sie mit der rechten Maustaste und wählen Sie "NuGet-Pakete verwalten ...". Suchen Sie im NuGet Package Manager-Fenster nach dem Paket Swashbuckle.AspNetCore und installieren Sie es. Alternativ können Sie das Paket wie unten gezeigt über die NuGet Package Manager-Konsole installieren.

PM> Install-Package Swashbuckle.AspNetCore

Das Swashbuckle.AspNetCore-Paket enthält die erforderlichen Tools zum Generieren von API-Dokumenten für ASP.Net Core.

Konfigurieren Sie die Swagger-Middleware in ASP.Net Core

Schreiben Sie zum Konfigurieren von Swagger den folgenden Code in die ConfigureServices-Methode. Beachten Sie, wie die AddSwaggerGen-Erweiterungsmethode verwendet wird, um die Metadaten für das API-Dokument anzugeben.

services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", neue Info

                {

                    Version = "v1",

                    Title = "Swagger Demo",

                    Description = "Swagger Demo für ValuesController",

                    TermsOfService = "Keine",

                    Kontakt = neuer Kontakt () {Name = "Joydip Kanjilal",

                    Email = "[email protected]",

                    URL = "www.google.com"}

                });

            });

Sie sollten die Swagger-Benutzeroberfläche auch in der unten gezeigten Configure-Methode aktivieren.

app.UseSwagger ();

app.UseSwaggerUI (c =>

{

   c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

});

Hier ist der vollständige Code der Startup-Klasse als Referenz.

using Microsoft.AspNetCore.Builder;

using Microsoft.AspNetCore.Hosting;

using Microsoft.AspNetCore.Mvc;

using Microsoft.Extensions.Configuration;

using Microsoft.Extensions.DependencyInjection;

using Swashbuckle.AspNetCore.Swagger;

Namespace SwaggerDemo

{

    Startup der öffentlichen Klasse

    {

        öffentlicher Start (IConfiguration Konfiguration)

        {

            Konfiguration = Konfiguration;

        }}

        öffentliche IConfiguration Konfiguration {get; }}

        public void ConfigureServices (IServiceCollection-Dienste)

        {

            services.AddMvc (). SetCompatibilityVersion

            (CompatibilityVersion.Version_2_2);   

            services.AddSwaggerGen (c =>

            {

                c.SwaggerDoc ("v1", neue Info

                {

                    Version = "v1",

                    Title = "Swagger Demo",

                    Description = "Swagger Demo für ValuesController",

                    TermsOfService = "Keine",

                    Kontakt = neuer Kontakt () {Name = "Joydip Kanjilal",

                    Email = "[email protected]",

                    URL = "www.google.com"

                }}

                });

            });

        }}

        public void Configure (IApplicationBuilder-App,

       IHostingEnvironment env)

        {

            if (env.IsDevelopment ())

            {

                app.UseDeveloperExceptionPage ();

            }}

            app.UseMvc ();

            app.UseSwagger ();

            app.UseSwaggerUI (c =>

            {

                c.SwaggerEndpoint ("/ swagger / v1 / swagger.json", "v1");

            });

        }}

    }}

}}

Dies ist alles, was Sie tun müssen, um mit Swagger zu beginnen.

Durchsuchen Sie die Swagger-Benutzeroberfläche Ihrer ASP.Net Core-App

Jetzt können wir die Anwendung ausführen und den Swagger-Endpunkt durchsuchen. Die Swagger-Benutzeroberfläche wird wie in Abbildung 1 unten angezeigt. Beachten Sie, wie Swagger unterschiedliche Farben für die HTTP-Verben GET, PUT, POST und DELETE verwendet. Sie können jeden der in Abbildung 1 gezeigten Endpunkte direkt über die Swagger-Benutzeroberfläche ausführen.

Erstellen Sie XML-Kommentare in den Aktionsmethoden Ihres Controllers

So weit, ist es gut. In dem zuvor generierten Swagger-Dokument gab es keine XML-Kommentare. Wenn Sie XML-Kommentare im Swagger-Dokument anzeigen möchten, schreiben Sie diese Kommentare einfach in die Aktionsmethoden Ihres Controllers.

Schreiben wir nun Kommentare für jede der Aktionsmethoden im ValuesController. Hier ist die aktualisierte Version des ValuesController mit XML-Kommentaren für jede der Aktionsmethoden.

  [Route ("api / [controller]")]

    [ApiController]

    öffentliche Klasse ValuesController: ControllerBase

    {

        ///

        /// Aktionsmethode ohne Argument abrufen

        ///

        ///

        [HttpGet]

        öffentliches Aktionsergebnis Bekommen()

        {

            neuen String zurückgeben [] {"value1", "value2"};

        }}

        ///

        /// Aktionsmethode abrufen, die eine Ganzzahl als Argument akzeptiert

        ///

        ///

        ///

        [HttpGet ("{id}")]

        public ActionResult Get (int id)

        {

            Rückgabewert";

        }}

        ///

        /// Post-Action-Methode zum Hinzufügen von Daten

        ///

        ///

        [HttpPost]

        public void Post (Zeichenfolgenwert [FromBody])

        {

        }}

        ///

        /// Setzen Sie eine Aktionsmethode, um Daten zu ändern

        ///

        ///

        ///

        [HttpPut ("{id}")]

        public void Put (int id, [FromBody] Zeichenfolgenwert)

        {

        }}

        ///

        /// Aktionsmethode löschen

        ///

        ///

        [HttpDelete ("{id}")]

        public void Delete (int id)

        {

        }}

    }}

Aktivieren Sie XML-Kommentare in Swagger

Beachten Sie, dass Swagger standardmäßig keine XML-Kommentare anzeigt. Sie müssen diese Funktion aktivieren. Klicken Sie dazu mit der rechten Maustaste auf Projekt, wählen Sie Eigenschaften aus und navigieren Sie zur Registerkarte Erstellen. Aktivieren Sie auf der Registerkarte Erstellen die Option "XML-Dokumentationsdatei", um den Speicherort anzugeben, an dem die XML-Dokumentationsdatei erstellt wird.

Sie sollten auch angeben, dass die XML-Kommentare beim Generieren des Swagger-Dokuments enthalten sein sollen, indem Sie den folgenden Code in die ConfigureServices-Methode schreiben.

c.IncludeXmlComments (@ "D: \ Projects \\ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");

Und das ist alles, was Sie tun müssen, um XML-Kommentare in Swagger zu aktivieren.

Stellen Sie die Start-URL für die App auf Swagger UI ein

Sie können die URL für den Start Ihrer Anwendung ändern, um anzugeben, dass die Swagger-Benutzeroberfläche beim Start der Anwendung geladen wird. Klicken Sie dazu mit der rechten Maustaste auf Projekt und wählen Sie Eigenschaften. Navigieren Sie dann zur Registerkarte Debug. Geben Sie zum Schluss den Wert für den Startbrowser als Prahlerei an (siehe Abbildung 2).

Wenn Sie die Anwendung erneut ausführen und zur Swagger-URL navigieren, sollte die Swagger-Benutzeroberfläche angezeigt werden (siehe Abbildung 3 unten). Beachten Sie diesmal die XML-Kommentare in jeder der API-Methoden.

Swashbuckle ist ein großartiges Tool zum Generieren von Swagger-Dokumenten für Ihre API. Am wichtigsten ist, dass Swashbuckle einfach zu konfigurieren und zu verwenden ist. Mit Swagger können Sie viel mehr tun, als wir hier gesehen haben. Sie können die Swagger-Benutzeroberfläche mithilfe von Cascading Style Sheets anpassen, Aufzählungswerte als Zeichenfolgenwerte anzeigen und verschiedene Swagger-Dokumente für verschiedene Versionen Ihrer API erstellen, um nur einige zu nennen.