Erste Schritte mit NSwag und ASP.NET CoreGet started with NSwag and ASP.NET Core

Von Christoph Nienaber, Rico Suter und Dave BrockBy Christoph Nienaber, Rico Suter, and Dave Brock

NSwag bietet die folgenden Funktionen:NSwag offers the following capabilities:

  • Die Möglichkeit, die Swagger-Benutzeroberfläche und den Swagger-Generator zu verwenden.The ability to utilize the Swagger UI and Swagger generator.
  • Flexible Codegenerierung.Flexible code generation capabilities.

Mit NSwag müssen Sie keine API— besitzen, sondern können APIs von Drittanbietern verwenden, die Swagger integrieren und eine Clientimplementierung generieren.With NSwag, you don't need an existing API—you can use third-party APIs that incorporate Swagger and generate a client implementation. Mit NSwag können Sie den Entwicklungszyklus beschleunigen und sich problemlos an API-Änderungen anpassen.NSwag allows you to expedite the development cycle and easily adapt to API changes.

Registrieren der NSwag-MiddlewareRegister the NSwag middleware

Die NSwag-Middleware wird für folgende Zwecke registriert:Register the NSwag middleware to:

  • Generieren Sie die Swagger-Spezifikation für die implementierte Web-API.Generate the Swagger specification for the implemented web API.
  • Stellen Sie die Swagger-Benutzeroberfläche zum Durchsuchen und Testen die Web-API bereit.Serve the Swagger UI to browse and test the web API.

Um NSwag mit ASP.NET Core-Middleware zu verwenden, installieren Sie das NuGet-Paket NSwag.AspNetCore.To use the NSwag ASP.NET Core middleware, install the NSwag.AspNetCore NuGet package. 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.This package contains the middleware to generate and serve the Swagger specification, Swagger UI (v2 and v3), and ReDoc UI.

Verwenden Sie einen der folgenden Ansätze, um das NuGet-Paket „NSwag“ zu installieren:Use one of the following approaches to install the NSwag NuGet package:

  • Aus dem Fenster Paket-Manager-Konsole:From the Package Manager Console window:

    • Navigieren Sie zu Ansicht > Weitere Fenster > Paket-Manager-Konsole.Go to View > Other Windows > Package Manager Console

    • Navigieren Sie zu dem Verzeichnis, in dem die TodoApi.csproj-Datei gespeichert ist.Navigate to the directory in which the TodoApi.csproj file exists

    • Führen Sie den folgenden Befehl aus:Execute the following command:

      Install-Package NSwag.AspNetCore
      
  • Aus dem Dialogfeld NuGet-Pakete verwalten:From the Manage NuGet Packages dialog:

    • Klicken Sie mit der rechten Maustaste unter Projektmappen-Explorer > NuGet-Pakete verwalten auf Ihr Projekt.Right-click the project in Solution Explorer > Manage NuGet Packages
    • Legen Sie die Paketquelle auf „nuget.org“ fest.Set the Package source to "nuget.org"
    • Geben Sie „NSwag.AspNetCore“ in das Suchfeld ein.Enter "NSwag.AspNetCore" in the search box
    • Wählen Sie das Paket „NSwag.AspNetCore“ auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.Select the "NSwag.AspNetCore" package from the Browse tab and click Install

Hinzufügen und Konfigurieren von Swagger-MiddlewareAdd and configure Swagger middleware

Sie können Swagger in Ihrer ASP.NET Core-App hinzufügen und konfigurieren, indem Sie die folgenden Schritte ausführen:Add and configure Swagger in your ASP.NET Core app by performing the following steps:

  • Registrieren Sie in der Startup.ConfigureServices-Methode die erforderlichen Swagger-Dienste:In the Startup.ConfigureServices method, register the required Swagger services:
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:In the Startup.Configure method, enable the middleware for serving the generated Swagger specification and the Swagger UI:
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.Launch the app. Navigieren Sie zu:Navigate to:
    • http://localhost:<port>/swagger, um die Swagger-Benutzeroberfläche anzuzeigen.http://localhost:<port>/swagger to view the Swagger UI.
    • http://localhost:<port>/swagger/v1/swagger.json, um die Swagger-Spezifikation anzuzeigen.http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

CodeerzeugungCode generation

Durch die Auswahl einer der folgenden Optionen können Sie die Funktion zur Codegenerierung von NSwag nutzen:You can take advantage of NSwag's code generation capabilities by choosing one of the following options:

Generieren von Code mit NSwagStudioGenerate code with NSwagStudio

  • Installieren Sie NSwagStudio anhand der Anweisungen im NSwagStudio-GitHub-Repository.Install NSwagStudio by following the instructions at the NSwagStudio GitHub repository. Auf der Releaseseite von NSwag können Sie eine XCOPY-Version herunterladen, die ohne Installation und Administratorrechte gestartet werden kann.On the NSwag release page you can download an xcopy version which can be started without installation and admin privileges.

  • Starten Sie NSwagStudio, und geben Sie die Datei-URL swagger.json in das Textfeld URL zur Spezifizierung des Swaggers ein.Launch NSwagStudio and enter the swagger.json file URL in the Swagger Specification URL text box. Beispiel: http://localhost:44354/swagger/v1/swagger.jsonFor example, 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.Click the Create local Copy button to generate a JSON representation of your Swagger specification.

    Erstellen einer lokalen Kopie der Swagger-Spezifikation

  • Klicken Sie im Bereich Ausgaben auf das Kontrollkästchen CSharp-Client.In the Outputs area, click the CSharp Client check box. Je nach Ihrem Projekt können Sie auch den TypeScript Client oder CSharp-Web-API-Controller auswählen.Depending on your project, you can also choose TypeScript Client or CSharp Web API Controller. Bei der Auswahl des CSharp-Web-API-Controllers erstellt eine Dienstspezifikation den Dienst neu, und dient als eine umgekehrte Generierung.If you select CSharp Web API Controller, a service specification rebuilds the service, serving as a reverse generation.

  • Klicken Sie auf Ausgaben generieren, um eine vollständige C#-Clientimplementierung des TodoApi.NSwag-Projekts durchzuführen.Click Generate Outputs to produce a complete C# client implementation of the TodoApi.NSwag project. Klicken Sie auf die Registerkarte CSharp-Client, damit der generierte Clientcode angezeigt wird:To see the generated client code, click the CSharp Client tab:

//----------------------
// <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.The C# client code is generated based on selections in the Settings tab. Modify the settings to perform tasks such as default namespace renaming and synchronous method generation.

  • Kopieren Sie den generierten C#-Code in eine Datei in das Clientprojekt, das die API verwendet.Copy the generated C# code into a file in the client project that will consume the API.
  • Verwendung der Web-API:Start consuming the 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-DokumentationCustomize API documentation

Swagger umfasst Optionen zum Dokumentieren des Objektmodells, um die Verwendung der Web-API zu vereinfachen.Swagger provides options for documenting the object model to ease consumption of the web API.

API-Informationen und -BeschreibungAPI info and description

In der Startup.ConfigureServices-Methode werden Informationen wie Autor, Lizenz und Beschreibung durch die Konfigurationsaktion hinzugefügt, die an die AddSwaggerDocument-Methode übergeben wird:In the Startup.ConfigureServices method, a configuration action passed to the AddSwaggerDocument method adds information such as the author, license, and description:

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:The Swagger UI displays the version's information:

Swagger-Benutzeroberfläche mit Versionsinformationen

XML-KommentareXML comments

Um XML-Kommentaren zu aktivieren, führen Sie die folgenden Schritte aus:To enable XML comments, perform the following steps:

  • Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie <project_name>.csproj bearbeiten aus.Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • Fügen Sie die hervorgehobenen Zeilen manuell der CSPROJ-Datei hinzu:Manually add the highlighted lines to the .csproj file:
<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.Right-click the project in Solution Explorer and select Properties
  • Überprüfen Sie das Feld XML-Dokumentationsdatei im Abschnitt Ausgabe der Registerkarte Erstellen.Check the XML documentation file box under the Output section of the Build tab

DatenanmerkungenData annotations

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.Because NSwag uses Reflection, and the recommended return type for web API actions is IActionResult, it can't infer what your action is doing and what it returns.

Betrachten Sie das folgende Beispiel:Consider the following example:

[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.The preceding action returns IActionResult, but inside the action it's returning either CreatedAtRoute or BadRequest. Verwenden Sie Datenanmerkungen, um Clients mitzuteilen, welche HTTP-Statuscodes diese Aktion in der Regel zurückgibt.Use data annotations to tell clients which HTTP status codes this action is known to return. Markieren Sie die Aktion mit den folgenden Attributen:Mark the action with the following attributes:

[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.Because NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>, it can only infer the return type defined by T. Sie können nicht automatisch andere mögliche Rückgabetypen ableiten.You can't automatically infer other possible return types.

Betrachten Sie das folgende Beispiel:Consider the following example:

[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.The preceding action returns ActionResult<T>. In der Aktion gibt sie CreatedAtRoute zurück.Inside the action, it's returning CreatedAtRoute. Da der Controller das [ApiController]-Attribut aufweist, ist auch eine BadRequest-Antwort möglich.Since the controller has the [ApiController] attribute, a BadRequest response is possible, too. Weitere Informationen finden Sie unter Automatische HTTP 400-Antworten.For more information, see Automatic HTTP 400 responses. Verwenden Sie Datenanmerkungen, um Clients mitzuteilen, welche HTTP-Statuscodes diese Aktion in der Regel zurückgibt.Use data annotations to tell clients which HTTP status codes this action is known to return. Markieren Sie die Aktion mit den folgenden Attributen:Mark the action with the following attributes:

[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.In ASP.NET Core 2.2 or later, you can use conventions instead of explicitly decorating individual actions with [ProducesResponseType]. Weitere Informationen finden Sie unter Verwenden von Web-API-Konventionen.For more information, see 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.The Swagger generator can now accurately describe this action, and generated clients know what they receive when calling the endpoint. Es wird empfohlen, alle Aktionen mit diesen Attributen zu markieren.As a recommendation, mark all actions with these attributes.

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).For guidelines on what HTTP responses your API actions should return, see the RFC 7231 specification.