Erste Schritte mit NSwag und ASP.NET Core

Von Christoph Nienaber, Rico Suter und Dave Brock

NSwag bietet die folgenden Funktionen:

  • Die Möglichkeit, die Swagger-Benutzeroberfläche und den Swagger-Generator zu verwenden.
  • Flexible Codegenerierung.

Mit NSwag müssen Sie keine API— besitzen, sondern können APIs von Drittanbietern verwenden, die Swagger integrieren und eine Clientimplementierung generieren. Mit NSwag können Sie den Entwicklungszyklus beschleunigen und sich problemlos an API-Änderungen anpassen.

Registrieren der NSwag-Middleware

Die NSwag-Middleware wird für folgende Zwecke registriert:

  • Generieren Sie die Swagger-Spezifikation für die implementierte Web-API.
  • Stellen Sie die Swagger-Benutzeroberfläche zum Durchsuchen und Testen die Web-API bereit.

Um NSwag mit ASP.NET Core-Middleware zu verwenden, installieren Sie das NuGet-Paket NSwag.AspNetCore. Dieses Paket enthält die Middleware zum Generieren und Bereitstellen der Swagger-Spezifikation, der Swagger-Benutzeroberfläche (v2 und v3) und der ReDoc-Benutzeroberfläche.

Verwenden Sie einen der folgenden Ansätze, um das NuGet-Paket „NSwag“ zu installieren:

  • Aus dem Fenster Paket-Manager-Konsole:

    • Navigieren Sie zu Ansicht > Weitere Fenster > Paket-Manager-Konsole.

    • Navigieren Sie zu dem Verzeichnis, in dem die TodoApi.csproj-Datei gespeichert ist.

    • Führen Sie den folgenden Befehl aus:

      Install-Package NSwag.AspNetCore
      
  • Aus dem Dialogfeld NuGet-Pakete verwalten:

    • Klicken Sie mit der rechten Maustaste unter Projektmappen-Explorer > NuGet-Pakete verwalten auf Ihr Projekt.
    • Legen Sie die Paketquelle auf „nuget.org“ fest.
    • Geben Sie „NSwag.AspNetCore“ in das Suchfeld ein.
    • Wählen Sie das Paket „NSwag.AspNetCore“ auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.

Hinzufügen und Konfigurieren von Swagger-Middleware

Sie können Swagger in Ihrer ASP.NET Core-App hinzufügen und konfigurieren, indem Sie die folgenden Schritte ausführen:

  • Registrieren Sie in der Startup.ConfigureServices-Methode die erforderlichen Swagger-Dienste:
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}
  • Aktivieren Sie die Middleware in der Startup.Configure-Methode, um die generierte Swagger-Spezifikation und die Swagger-Benutzeroberfläche zu verarbeiten:
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}
  • Starten Sie die App. Navigieren Sie zu:
    • http://localhost:<port>/swagger, um die Swagger-Benutzeroberfläche anzuzeigen.
    • http://localhost:<port>/swagger/v1/swagger.json, um die Swagger-Spezifikation anzuzeigen.

Codeerzeugung

Durch die Auswahl einer der folgenden Optionen können Sie die Funktion zur Codegenerierung von NSwag nutzen:

Generieren von Code mit NSwagStudio

  • Installieren Sie NSwagStudio anhand der Anweisungen im NSwagStudio-GitHub-Repository. Auf der Releaseseite von NSwag können Sie eine XCOPY-Version herunterladen, die ohne Installation und Administratorrechte gestartet werden kann.

  • Starten Sie NSwagStudio, und geben Sie die Datei-URL swagger.json in das Textfeld URL zur Spezifizierung des Swaggers ein. Beispiel: http://localhost:44354/swagger/v1/swagger.json

  • Klicken Sie auf die Schaltfläche Lokale Kopie erstellen, um eine JSON-Darstellung Ihrer Swagger-Spezifikation zu generieren.

    Erstellen einer lokalen Kopie der Swagger-Spezifikation

  • Aktivieren Sie im Bereich Ausgaben das Kontrollkästchen CSharp-Client. Je nach Ihrem Projekt können Sie auch den TypeScript Client oder CSharp-Web-API-Controller auswählen. Bei der Auswahl des CSharp-Web-API-Controllers erstellt eine Dienstspezifikation den Dienst neu, und dient als eine umgekehrte Generierung.

  • Klicken Sie auf Ausgaben generieren, um eine vollständige C#-Clientimplementierung des TodoApi.NSwag-Projekts durchzuführen. Klicken Sie auf die Registerkarte CSharp-Client, damit der generierte Clientcode angezeigt wird:

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

Tipp

Die C#-Clientcode wird auf Grundlage Ihrer Auswahl auf der Registerkarte Einstellungen generiert. Ändern Sie die Einstellungen, um Aufgaben wie das Umbenennen von Standardnamespaces und die Generierung von synchronen Methoden auszuführen.

  • Kopieren Sie den generierten C#-Code in eine Datei in das Clientprojekt, das die API verwendet.
  • Verwendung der Web-API:
 var todoClient = new TodoClient();

// Gets all to-dos from the API
 var allTodos = await todoClient.GetAllAsync();

 // Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

Anpassen der API-Dokumentation

Swagger umfasst Optionen zum Dokumentieren des Objektmodells, um die Verwendung der Web-API zu vereinfachen.

API-Informationen und -Beschreibung

In der Startup.ConfigureServices-Methode werden Informationen wie Autor, Lizenz und Beschreibung durch die Konfigurationsaktion hinzugefügt, die an die AddSwaggerDocument-Methode übergeben wird:

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Auf der Swagger-Benutzeroberfläche werden die Versionsinformationen angezeigt:

Swagger-Benutzeroberfläche mit Versionsinformationen

XML-Kommentare

Um XML-Kommentaren zu aktivieren, führen Sie die folgenden Schritte aus:

  • Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie <project_name>.csproj bearbeiten aus.
  • Fügen Sie die hervorgehobenen Zeilen manuell der CSPROJ-Datei hinzu:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Eigenschaften aus.
  • Überprüfen Sie das Feld XML-Dokumentationsdatei im Abschnitt Ausgabe der Registerkarte Erstellen.

Datenanmerkungen

Da NSwag Reflektion verwendet, und der empfohlene Rückgabetyp ist für Web-API-Aktionen IActionResult, kann nicht abgeleitet werden, was Ihre Aktion ausführt und was zurückgegeben wird.

Betrachten Sie das folgende Beispiel:

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Die vorherige Aktion gibt IActionResult zurück. Innerhalb der Aktion gibt sie jedoch CreatedAtRoute oder BadRequest zurück. Verwenden Sie Datenanmerkungen, um Clients mitzuteilen, welche HTTP-Statuscodes diese Aktion in der Regel zurückgibt. Markieren Sie die Aktion mit den folgenden Attributen:

[ProducesResponseType(typeof(TodoItem), StatusCodes.Status201Created)]  // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]                 // BadRequest

Da NSwag Reflection verwendet und der empfohlene Rückgabetyp für Web-API-Aktionen ActionResult<T> ist, kann nur der von T definierte Rückgabetyp abgeleitet werden. Sie können nicht automatisch andere mögliche Rückgabetypen ableiten.

Betrachten Sie das folgende Beispiel:

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

Die vorherige Aktion gibt ActionResult<T> zurück. In der Aktion gibt sie CreatedAtRoute zurück. Da der Controller das [ApiController]-Attribut aufweist, ist auch eine BadRequest-Antwort möglich. Weitere Informationen finden Sie unter Automatische HTTP 400-Antworten. Verwenden Sie Datenanmerkungen, um Clients mitzuteilen, welche HTTP-Statuscodes diese Aktion in der Regel zurückgibt. Markieren Sie die Aktion mit den folgenden Attributen:

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

In ASP.NET Core 2.2 oder höher können Sie stattdessen Konventionen verwenden, um einzelne Aktionen explizit mit [ProducesResponseType] zu ergänzen. Weitere Informationen finden Sie unter Verwenden von Web-API-Konventionen.

Der Swagger-Generator kann diese Aktion nun genau beschreiben, und generierte Clients wissen, was sie beim Aufrufen des Endpunkts empfangen. Es wird empfohlen, alle Aktionen mit diesen Attributen zu markieren.

Weitere Informationen zu den Richtlinien dazu, welche HTTP-Antworten Ihre API-Aktionen zurückgeben sollten, finden Sie in der RFC 7231 specification (Spezifikation von RFC 7231).