Erste Schritte mit NSwag und ASP.NET Core

Von Christoph Nienaber, Rico Suter und Dave Brock

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

NSwag bietet die folgenden Funktionen:

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

Mit NSwag brauchen Sie keine vorhandene API. Sie können APIs von Drittanbietern verwenden, die Swagger einbinden und eine Client Implementierung generieren. Mit NSwag können Sie den Entwicklungszyklus beschleunigen und sich problemlos an API-Änderungen anpassen.

Paketinstallation

Installieren Sie NSwag für Folgendes:

• 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.
• Stellen Sie ReDoc bereit, um die API-Dokumentation für die Web-API hinzuzufügen.

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. NSwag 14 unterstützt nur v3 der Swagger UI-Spezifikation.

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

Visual Studio

• Aus dem Fenster Paket-Manager-Konsole:

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

  • Navigieren Sie zu dem Verzeichnis, in dem die NSwagSample.csproj 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.

Visual Studio für Mac

• Klicken Sie mit der rechten Maustaste auf den Ordner Pakete unter Lösungspad>Pakete hinzufügen... .
• Legen Sie im Fenster Pakete hinzufügen das Dropdownmenü Quelle auf „nuget.org“ fest.
• Geben Sie „NSwag.AspNetCore“ in das Suchfeld ein.
• Wählen Sie das Paket „NSwag.AspNetCore“ aus dem Ergebnisbereich aus, und klicken Sie auf Paket hinzufügen.

Visual Studio Code

Führen Sie folgenden Befehl aus dem integrierten Terminal aus:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

.NET CLI

Führen Sie den folgenden Befehl aus:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

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:

• Fügen Sie den OpenApi-Generator zur Sammlung „services“ in Program.cs hinzu:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();

• Aktivieren Sie die Middleware für die Bereitstellung der generierten OpenApi-Spezifikation, der Swagger-Benutzeroberfläche und der ReDoc-Benutzeroberfläche, auch in Program.cs:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

• 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:

• NSwagStudio: Dies ist eine Windows-Desktop-App zum Generieren von API-Clientcode in C# und TypeScript.
• Die NuGet-Pakete NSwag.CodeGeneration.CSharp oder NSwag.CodeGeneration.TypeScript, um Code innerhalb des Projekts zu generieren.
• NSwag über die Befehlszeile.
• Das NuGet-Paket NSwag.MSBuild.
• Unchase OpenAPI (Swagger) Connected Service: Dies ist ein mit Visual Studio verbundener Dienst zum Generieren von API-Clientcode in C# oder TypeScript. Es werden auch C#-Controller für OpenAPI-Dienste mit NSwag generiert.

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:5232/swagger/v1/swagger.json.
• Klicken Sie auf die Schaltfläche Lokale Kopie erstellen, um eine JSON-Darstellung Ihrer Swagger-Spezifikation zu generieren.

• 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:

namespace MyNamespace
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
    public partial class TodoClient
    {
    #pragma warning disable 8618 // Set by constructor via BaseUrl property
        private string _baseUrl;
    #pragma warning restore 8618 // Set by constructor via BaseUrl property
        private System.Net.Http.HttpClient _httpClient;
        private static System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(CreateSerializerSettings, true);

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            BaseUrl = "http://localhost:5232";
            _httpClient = httpClient;
        }

        private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
        {
            var settings = new Newtonsoft.Json.JsonSerializerSettings();
            UpdateJsonSerializerSettings(settings);
            return settings;
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set
            {
                _baseUrl = value;
                if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                    _baseUrl += '/';
            }
        }
        // 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(new HttpClient());

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

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

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

Anpassen der API-Dokumentation

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

API-Informationen und -Beschreibung

Aktualisieren Sie AddOpenApiDocument in Program.cs, um die Dokumentinformationen der Web-API zu konfigurieren, und fügen Sie weitere Informationen wie Autor, Lizenz und Beschreibung hinzu. Importieren Sie zuerst den Namespace NSwag, um die OpenApi-Klassen zu verwenden.

using NSwag;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApiDocument(options => {
     options.PostProcess = document =>
     {
         document.Info = new OpenApiInfo
         {
             Version = "v1",
             Title = "ToDo API",
             Description = "An ASP.NET Core Web API for managing ToDo items",
             TermsOfService = "https://example.com/terms",
             Contact = new OpenApiContact
             {
                 Name = "Example Contact",
                 Url = "https://example.com/contact"
             },
             License = new OpenApiLicense
             {
                 Name = "Example License",
                 Url = "https://example.com/license"
             }
         };
     };
});

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

XML-Kommentare

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

Visual Studio

• Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Edit <project_name>.csproj aus.
• Fügen Sie die hervorgehobenen Zeilen manuell der .csproj-Datei hinzu:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio für Mac

• Drücken und halten Sie im Lösungspad die CONTROL-Taste, und klicken Sie auf den Projektnamen. Navigieren Sie zu Extras>Datei bearbeiten.
• Fügen Sie die hervorgehobenen Zeilen manuell der .csproj-Datei hinzu:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

Fügen Sie die hervorgehobenen Zeilen manuell der .csproj-Datei hinzu:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

.NET CLI

Fügen Sie die hervorgehobenen Zeilen manuell der .csproj-Datei hinzu:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Das Aktivieren von XML-Kommentaren stellt Debuginformationen zu nicht-dokumentierten öffentlichen Typen und Members bereit. Auf nicht dokumentierte Typen und Member wird durch die Warnmeldung verwiesen. Die folgende Meldung macht z.B. durch den Warnungscode 1591 auf einen Verstoß aufmerksam:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoContext'

Um Warnungen projektübergreifend zu unterdrücken, definieren Sie eine Liste der zu ignorierenden Warnungscodes (mit Semikolon als Trennzeichen). Das Anfügen von Warnungscodes an $(NoWarn); gilt auch für die C#-Standardwerte.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Um Warnungen nur für bestimmte Member zu unterdrücken, schließen Sie den Code in #pragma warning-Präprozessordirektiven ein. Dieser Ansatz eignet sich für Code, der nicht über die API-Dokumentation verfügbar gemacht werden soll. Im folgenden Beispiel wird der Warnungscode CS1591 für die gesamte Klasse TodoContext ignoriert. Das Erzwingen des Warnungscodes wird am Ende der Klassendefinition wiederhergestellt. Geben Sie mehrere Warnungscodes in einer kommagetrennten Liste an.

namespace NSwagSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Datenanmerkungen

Markieren Sie das Modell mit Attributen, die sich im Namespace System.ComponentModel.DataAnnotations befinden, um die Swagger-UI-Komponenten zu steuern.

Fügen Sie das [Required]-Attribut der Name-Eigenschaft der TodoItem-Klasse hinzu:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace NSwagSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Das Vorhandensein dieses Attributs ändert das Verhalten der Benutzeroberfläche und des zugrunde liegenden JSON-Schemas:

"TodoItem": {
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "isComplete": {
      "type": "boolean",
      "default": false
    }
  }
}

Mit zunehmender Verwendung von Datenanmerkungen in der Web-API werden die UI- und API-Hilfeseiten beschreibender und nützlicher.

Beschreiben von Antworttypen

Entwickler, die eine Web-API nutzen, interessieren sich vor allem dafür, welche Antworttypen und Fehlercodes zurückgegeben werden (wenn diese nicht dem Standard entsprechen). Die Antworttypen und Fehlercodes sind in den XML-Kommentaren und Datenanmerkungen gekennzeichnet.

Die Aktion Create gibt bei einer erfolgreichen Anforderung den Statuscode „HTTP 201“ zurück. Der Statuscode „HTTP 400“ wird zurückgegeben, wenn der gesendete Anforderungstext null ist. Ohne richtige Dokumentation in der Swagger-Benutzeroberfläche fehlt dem Consumer das Wissen über diese erwarteten Ergebnisse. Sie können dieses Problem beheben, indem Sie die hervorgehobenen Zeilen im folgenden Beispiel hinzufügen:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Die Swagger-Benutzeroberfläche dokumentiert nun deutlich die erwarteten HTTP-Antwortcodes (und die XML-Kommentare werden ebenfalls angezeigt):

Alternativ können Konventionen verwendet werden, um einzelne Aktionen explizit mit [ProducesResponseType] zu ergänzen. Weitere Informationen finden Sie unter Verwenden von Web-API-Konventionen.

ReDoc

ReDoc ist eine Alternative zur Swagger-Benutzeroberfläche. Sie ist ähnlich, da sie mit der OpenAPI-Spezifikation auch eine Dokumentationsseite für die Web-API bereitstellt. Der Unterschied besteht darin, dass sich die ReDoc-Benutzeroberfläche stärker auf die Dokumentation konzentriert. Sie stellt keine interaktive Benutzeroberfläche zum Testen der API bereit.

Um ReDoc zu aktivieren, fügen Sie die Middleware zu Program.cs hinzu:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi(); // UseSwaggerUI is called only in Development.
    
    // Add ReDoc UI to interact with the document
    // Available at: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Führen Sie die Anwendung aus, und navigieren Sie zu http://localhost:<port>/redoc, um die ReDoc-Benutzeroberfläche anzuzeigen: