Übung: Aktivieren der OpenAPI-Dokumentation in einer ASP.NET Core-Web-API-App

Abgeschlossen

Ihr Unternehmen verfügt über eine API namens PrintFramerAPI, mit der die Kosten eines Bilderrahmens anhand der Größe der Rahmenabmessungen berechnet werden. Intern weiß Ihr kleines Team, wie die API zu verwenden ist. Damit die API zum Vorteil des Unternehmens sowie von Dritten genutzt werden kann, muss sie dokumentiert werden. Da diese API eine ASP.NET Core-API ist, möchten Sie die API-Dokumentation über OpenAPI verfügbar machen.

In dieser Übung dokumentieren Sie eine ASP.NET Core-Web-API mit OpenAPI und testen Swagger UI und Swashbuckle in einem realen Beispiel. Zunächst erstellen wir ein ASP.NET Core-Web-API-Projekt.

Hinweis

In diesem Modul wird die .NET-CLI (Befehlszeilenschnittstelle) und Visual Studio Code für die lokale Entwicklung verwendet. Nach Abschluss dieses Moduls können Sie die Konzepte in einer Entwicklungsumgebung wie Visual Studio (Windows), Visual Studio für Mac (macOS) oder bei der Weiterentwicklung mit Visual Studio Code (Windows, Linux und macOS) anwenden.

Herunterladen des Web-API-Beispielprojekts in Visual Studio Code

1. Öffnen Sie eine neue Instanz von Visual Studio Code.

2. Wählen Sie Ansichtund dann Terminal aus, um das Terminalfenster zu öffnen.

3. (Optional) Wechseln Sie zu einem Verzeichnis, in das Sie die Dateien kopieren möchten, z. B. c:\MyProjects.

4. Führen Sie den folgenden git clone-Befehl im Terminalfenster aus, um das Web-API-Projekt aus GitHub zu klonen.

   git clone https://github.com/MicrosoftDocs/mslearn-improve-api-developer-experience-with-swagger && cd mslearn-improve-api-developer-experience-with-swagger/PrintFramerAPI
   

5. Öffnen Sie das Projekt in Visual Studio Code mit dem folgenden Terminalbefehl.

   code -a .
   

Erstmaliges Ausführen der Web-API

1. Geben Sie im Visual Studio Code-Terminalfenster den folgenden Befehl ein:

   dotnet run
   

2. Navigieren Sie nach Abschluss der Ausgabe des Befehls zu: http://localhost:5000/api/priceframe/6/17

   Wenn Sie im Browser zu der Adresse navigieren, sollte die Meldung The cost of a 6x17 frame is $20.00 angezeigt werden.

Sie kennen die Form der API, seit Sie sie erstellt haben. Einem externen Entwickler, der die API nutzen möchte, ist diese jedoch nicht bekannt. Sie können diese Entwickler unterstützen, indem Sie Dokumentationen zur API mithilfe von OpenAPI und unter Verwendung von Swashbuckle mit einer Open-Source-Version der Swagger-Tools verfügbar machen.

Hinzufügen der Swagger-Bibliothek zur Lösung

1. Fügen Sie Swashbuckle zu Ihrem Projekt hinzu, indem Sie den dotnet add package-Befehl ausführen.

   dotnet add package Swashbuckle.AspNetCore
   

2. Öffnen Sie die Datei Startup.cs.

3. Fügen Sie am Anfang der Datei einen weiteren using-Eintrag hinzu:

   using Microsoft.OpenApi.Models;
   

4. Ersetzen Sie die ConfigureServices(IServiceCollection services)-Methode durch die folgende Implementierung, um den Swagger-Generator zur Dienstsammlung hinzuzufügen.

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllers();
   
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
       });
   }
   

5. Aktivieren Sie in der Configure-Methode in Startup.cs die Middleware für Swagger UI, indem Sie useSwagger und useSwaggerUI wie dargestellt dem folgenden Codeausschnitt hinzufügen.

   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
       if (env.IsDevelopment())
       {
           app.UseSwagger();
           app.UseSwaggerUI(c =>
           {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
           });
   
           app.UseDeveloperExceptionPage();
       }
   
       app.UseHttpsRedirection();
   
       app.UseRouting();
   
       app.UseAuthorization();
   
       app.UseEndpoints(endpoints =>
       {
           endpoints.MapControllers();
       }); 
   }
   

6. Speichern Sie Ihre Änderungen im Editor.

7. Um diese Änderungen anzuzeigen, führen Sie die ASP.NET-Anwendung lokal aus. Geben Sie in das Terminalfenster in Visual Studio Code den folgenden Befehl ein:

   dotnet run
   

8. Navigieren Sie in einem Browser zu http://localhost:5000/swagger/v1/swagger.json.

   Die Antwort, die wir dieses Mal im Browser erhalten, ist ein Dokument, das die Endpunkte der API so ähnlich wie in der folgenden Antwort beschreibt.

   

Weiter