Übung: Verwenden von Swashbuckle zum Erstellen eines Open API-Dokuments

Abgeschlossen

In dieser Übung fügen Sie einer ASP.NET Core-Web-API-Anwendung Swagger und die Swagger-Benutzeroberfläche hinzu. Die Swagger-Tools unterstützen Sie beim Erstellen des OpenAPI-Dokuments mit der Beschreibung Ihrer Web-API.

Hinweis

Laden Sie den Quellcode auf Ihren lokalen Computer herunter, um diese Übung nachvollziehen zu können. Nachdem Sie die Datei heruntergeladen haben, müssen Sie sie entzippen.

Download: ASP.NET Core-Web-API-Anwendung.

1. Wählen Sie die Schaltfläche Rohdatendatei herunterladen aus.
2. Entzippen Sie die Datei exercise.zip.

Hinzufügen der Swagger-Tools

1. Öffnen Visual Studio, und suchen Sie die ASP.NET Core-Web-API-App.

   

2. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie dann das Menü NuGet-Pakete verwalten aus.

   

3. Suchen Sie im NuGet-Paket-Manager nach Swashbuckle.AspNetCore. Wählen Sie das Paket aus, und installieren Sie es.

   

   Das NuGet-Paket wurde jetzt installiert. Schließen Sie die Registerkarte NuGet-Paket-Manager.

Konfigurieren von Swashbuckle zum Generieren eines OpenAPI-Dokuments

1. Öffnen Sie die Datei Startup.cs.

   

2. Fügen Sie die folgende Anweisung direkt oberhalb der Zeile namespace InventoryManagement.ApiApp ein.

   /* === using directive BEGIN === */
   using Microsoft.OpenApi.Models;
   /* === using directive END === */
   

3. Ersetzen Sie den Code in der ConfigureServices(IServiceCollection)-Methode durch den folgenden Code:

       services.AddControllers();
   
       /* === SwaggerGen BEGIN === */
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
       });
       /* === SwaggerGen END === */
   

4. Suchen Sie in der Configure(IApplicationBuilder, IWebHostEnvironment)-Methode nach der bedingten Anweisung if (env.IsDevelopment()), und ersetzen Sie alles über dieser Anweisung durch den folgenden Code:

       /* === SwaggerUI BEGIN === */
       app.UseSwagger(c =>
       {
           c.PreSerializeFilters.Add((swagger, httpReq) => {
               var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
               swagger.Servers = new List<OpenApiServer>() { server };
           });
       });
       app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
       /* === SwaggerUI END === */
   

   Hinweis

   Es ist sehr wichtig, dass Swagger-Endpunkte nur in der Entwicklungsumgebung aktiviert werden. Andernfalls könnte Ihre API für die Öffentlichkeit verfügbar gemacht werden.

   Sie haben die Aktivierung des OpenAPI-Dokumentfeatures für Ihre ASP.NET Core-Web-API-App abgeschlossen. Speichern Sie die Datei Startup.cs. Ihre Änderungen sollten ähnlich wie der folgende Screenshot aussehen.

   

Generieren der OpenAPI-Dokumentdatei

1. Wählen Sie oben in der Mitte von Visual Studio die Schaltfläche „Debuggen“ aus.

   

   Der Webbrowser wird automatisch geöffnet und zeigt die Seite mit der Swagger-Benutzeroberfläche an.

   

   Möglicherweise wird die Fehlerseite 404 angezeigt. Geben Sie in diesem Fall die URL (https://localhost:<port_number>/swagger) in die Adressleiste Ihres Browsers ein. Im folgenden Screenshot lautet die URL zum Beispiel https://localhost:44371/swagger.

   

2. Wählen Sie den Link aus, um die OpenAPI-Dokumentseite zu öffnen.

   

3. Das OpenAPI-Dokument wird direkt gerendert.

   

Ihre ASP.NET Core-Web-API-App kann jetzt das OpenAPI-Dokument generieren.