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

Von Shayne Boyer und Scott AddieBy Shayne Boyer and Scott Addie

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Es gibt drei Hauptkomponenten von Swashbuckle:There are three main components to Swashbuckle:

  • Swashbuckle.AspNetCore.Swagger: ein Swagger-Objektmodell und eine Swagger-Middleware, um SwaggerDocument-Objekte als JSON-Endpunkte verfügbar zu machen.Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.

  • Swashbuckle.AspNetCore.SwaggerGen: ein Swagger-Generator, der SwaggerDocument-Objekte direkt aus Routen, Controllern und Modellen erstellt.Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models. Dieser wird üblicherweise mit der Middleware für den Swagger-Endpunkt kombiniert, um Swagger-JSONs automatisch verfügbar zu machen.It's typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: eine eingebettete Version des Swagger UI-Tools.Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. Diese interpretiert JSON-Daten von Swagger zur Erstellung einer umfassenden und anpassbaren Benutzeroberfläche, auf der Web-API-Funktionen beschrieben werden.It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. Es enthält integrierte Testumgebungen für die öffentlichen Methoden.It includes built-in test harnesses for the public methods.

PaketinstallationPackage installation

Swashbuckle kann mit folgenden Vorgehensweisen hinzugefügt werden:Swashbuckle can be added with the following approaches:

  • 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 Swashbuckle.AspNetCore -Version 5.5.0
      
  • 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"
    • Stellen Sie sicher, dass die Option „Vorabversion einschließen“ aktiviert ist.Ensure the "Include prerelease" option is enabled
    • Geben Sie „Swashbuckle.AspNetCore“ in das Suchfeld ein.Enter "Swashbuckle.AspNetCore" in the search box
    • Wählen Sie das aktuelle Paket „Swashbuckle.AspNetCore“ auf der Registerkarte Durchsuchen aus, und klicken Sie auf Installieren.Select the latest "Swashbuckle.AspNetCore" package from the Browse tab and click Install

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

Fügen Sie den Swagger-Generator zu der services-Sammlung in der Startup.ConfigureServices-Methode hinzu:Add the Swagger generator to the services collection in the Startup.ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen();
}

Aktivieren Sie die Middleware in der Startup.Configure-Methode, um das generierte JSON-Dokument und die Swagger-Benutzeroberfläche bereitzustellen:In the Startup.Configure method, enable the middleware for serving the generated JSON document and the Swagger UI:

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}
public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Hinweis

Swashbuckle basiert beim Ermitteln der Routen und Endpunkte auf dem Microsoft.AspNetCore.Mvc.ApiExplorer von MVC.Swashbuckle relies on MVC's Microsoft.AspNetCore.Mvc.ApiExplorer to discover the routes and endpoints. Wenn das Projekt AddMvc aufruft, werden Routen und Endpunkte automatisch erkannt.If the project calls AddMvc, routes and endpoints are discovered automatically. Beim Aufruf von AddMvcCore muss die AddApiExplorer-Methode explizit aufgerufen werden.When calling AddMvcCore, the AddApiExplorer method must be explicitly called. Weitere Informationen finden Sie unter Swashbuckle, ApiExplorer, and Routing (Swashbuckle, ApiExplorer und Routing).For more information, see Swashbuckle, ApiExplorer, and Routing.

Der obige UseSwaggerUI-Methodenaufruf aktiviert die Middleware für statische Dateien.The preceding UseSwaggerUI method call enables the Static File Middleware. Wenn .NET Framework oder .NET Core 1.x die Zielkomponente ist, müssen Sie Ihrem Projekt das NuGet-Paket Microsoft.AspNetCore.StaticFiles hinzufügen.If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.

Starten Sie die App, und navigieren Sie zu http://localhost:<port>/swagger/v1/swagger.json.Launch the app, and navigate to http://localhost:<port>/swagger/v1/swagger.json. Das generierte Dokument mit der Beschreibung der Endpunkte wird entsprechend der OpenAPI-Spezifikation (openapi.json) angezeigt.The generated document describing the endpoints appears as shown in OpenAPI specification (openapi.json).

Die Swagger-Benutzeroberfläche ist unter http://localhost:<port>/swagger verfügbar.The Swagger UI can be found at http://localhost:<port>/swagger. Mit der Swagger-Benutzeroberfläche können Sie die API kennenlernen und sie in andere Programme integrieren.Explore the API via Swagger UI and incorporate it in other programs.

Tipp

Legen Sie für die Eigenschaft RoutePrefix eine leere Zeichenfolge fest, um die Swagger-Benutzeroberfläche im App-Stamm (http://localhost:<port>/) bereitzustellen:To serve the Swagger UI at the app's root (http://localhost:<port>/), set the RoutePrefix property to an empty string:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

Wenn Sie Verzeichnisse mit ISS oder einem Reverseproxy verwenden, legen Sie den Swagger-Endpunkt mit dem Präfix ./ auf einen relativen Pfad fest.If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the ./ prefix. Beispielsweise ./swagger/v1/swagger.json.For example, ./swagger/v1/swagger.json. /swagger/v1/swagger.json weist die App an, am ursprünglichen Stamm der URL nach einer JSON-Datei (und ggf. nach einem Routenpräfix) zu suchen.Using /swagger/v1/swagger.json instructs the app to look for the JSON file at the true root of the URL (plus the route prefix, if used). Verwenden Sie z. B. http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json statt http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.For example, use http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json instead of http://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Hinweis

Standardmäßig generiert Swashbuckle Swagger-JSON-Code in Version 3.0 der Spezifikation — offiziell als OpenAPI-Spezifikation bezeichnet.By default, Swashbuckle generates and exposes Swagger JSON in version 3.0 of the specification—officially called the OpenAPI Specification. Um die Abwärtskompatibilität zu unterstützen, können Sie stattdessen JSON im 2.0-Format verfügbar machen.To support backwards compatibility, you can opt into exposing JSON in the 2.0 format instead. Dieses 2.0-Format ist wichtig für Integrationen wie Microsoft Power Apps und Microsoft Flow, die derzeit OpenAPI-Version 2.0 unterstützen.This 2.0 format is important for integrations such as Microsoft Power Apps and Microsoft Flow that currently support OpenAPI version 2.0. Um das 2.0-Format zu verwenden, legen Sie die SerializeAsV2-Eigenschaft in Startup.Configure fest:To opt into the 2.0 format, set the SerializeAsV2 property in Startup.Configure:

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger(c =>
    {
        c.SerializeAsV2 = true;
    });

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Anpassen und ErweiternCustomize and extend

Swagger stellt Optionen für das Dokumentieren des Objektmodells und das Anpassen der Benutzeroberfläche bereit, damit diese mit Ihrem Design übereinstimmt.Swagger provides options for documenting the object model and customizing the UI to match your theme.

Fügen Sie in der Startup-Klasse die folgenden Namespaces hinzu:In the Startup class, add the following namespaces:

using System;
using System.Reflection;
using System.IO;

API-Informationen und -BeschreibungAPI info and description

Durch die Konfigurationsaktion, die an die AddSwaggerGen-Methode übergeben wird, werden Informationen wie Autor, Lizenz und Beschreibung hinzugefügt:The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

Importieren Sie in der Startup-Klasse den folgenden Namespace zur Verwendung der OpenApiInfo-Klasse:In the Startup class, import the following namespace to use the OpenApiInfo class:

using Microsoft.OpenApi.Models;

Ändern Sie die in der Benutzeroberfläche angezeigten Informationen mithilfe der OpenApiInfo-Klasse:Using the OpenApiInfo class, modify the information displayed in the UI:

// Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("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: Beschreibung, Autor, Link „Mehr anzeigen“

XML-KommentareXML comments

XML-Kommentare können mithilfe der folgenden Ansätze aktiviert werden:XML comments can be enabled with the following approaches:

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

Das Aktivieren von XML-Kommentaren stellt Debuginformationen zu nicht-dokumentierten öffentlichen Typen und Members bereit.Enabling XML comments provides debug information for undocumented public types and members. Auf nicht dokumentierte Typen und Member wird durch die Warnmeldung verwiesen.Undocumented types and members are indicated by the warning message. Die folgende Meldung macht z.B. durch den Warnungscode 1591 auf einen Verstoß aufmerksam:For example, the following message indicates a violation of warning code 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

Um Warnungen projektübergreifend zu unterdrücken, definieren Sie eine Liste der zu ignorierenden Warnungscodes (mit Semikolon als Trennzeichen).To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file. Das Anfügen von Warnungscodes an $(NoWarn); gilt auch für die C#-Standardwerte.Appending the warning codes to $(NoWarn); applies the C# default values too.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
<PropertyGroup>
  <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  <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.To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives. 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 Program ignoriert.This approach is useful for code that shouldn't be exposed via the API docs. In the following example, warning code CS1591 is ignored for the entire Program class. Das Erzwingen des Warnungscodes wird am Ende der Klassendefinition wiederhergestellt.Enforcement of the warning code is restored at the close of the class definition. Geben Sie mehrere Warnungscodes in einer kommagetrennten Liste an.Specify multiple warning codes with a comma-delimited list.

namespace TodoApi
{
#pragma warning disable CS1591
    public class Program
    {
        public static void Main(string[] args) =>
            BuildWebHost(args).Run();

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
#pragma warning restore CS1591
}

Konfigurieren Sie Swagger so, dass die XML-Datei verwendet wird, die nach Befolgen der vorherigen Anweisungen generiert wurde.Configure Swagger to use the XML file that's generated with the preceding instructions. Bei Linux oder anderen Betriebssystemen als Windows können bei Dateinamen und -pfaden Groß-/Kleinbuchstaben berücksichtigt werden.For Linux or non-Windows operating systems, file names and paths can be case-sensitive. Die Datei TodoApi.XML ist beispielsweise unter Windows, nicht aber unter CentOS gültig.For example, a TodoApi.XML file is valid on Windows but not CentOS.

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "ToDo API",
            Description = "A simple example ASP.NET Core Web API",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Shayne Boyer",
                Email = string.Empty,
                Url = new Uri("https://twitter.com/spboyer"),
            },
            License = new OpenApiLicense
            {
                Name = "Use under LICX",
                Url = new Uri("https://example.com/license"),
            }
        });

        // Set the comments path for the Swagger JSON and UI.
        var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}

Im vorangehenden Codeausschnitt wurde durch Reflektion ein XML-Dateiname erstellt, der dem Namen des Web-API-Projekts entspricht.In the preceding code, Reflection is used to build an XML file name matching that of the web API project. Die AppContext.BaseDirectory-Eigenschaft wird verwendet, um einen Pfad zu der XML-Datei zu erstellen.The AppContext.BaseDirectory property is used to construct a path to the XML file. Einige Swagger-Features (z.B. Schemas von Eingabeparametern oder HTTP-Methoden und Antwortcodes aus den jeweiligen Attributen) funktionieren ohne XML-Dokumentationsdatei.Some Swagger features (for example, schemata of input parameters or HTTP methods and response codes from the respective attributes) work without the use of an XML documentation file. Für die meisten Funktionen, nämlich Methodenzusammenfassungen und Beschreibungen von Parametern und Antwortcodes, ist die Verwendung einer XML-Datei unerlässlich.For most features, namely method summaries and the descriptions of parameters and response codes, the use of an XML file is mandatory.

Das Hinzufügen von Kommentaren mit drei Schrägstrichen zu einer Aktion erweitert die Swagger-Benutzeroberfläche, indem die Beschreibung zum Header des Abschnitts hinzugefügt wird.Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Fügen Sie nun über der Delete-Aktion ein <summary>-Element hinzu:Add a <summary> element above the Delete action:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>        
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    var todo = _context.TodoItems.Find(id);

    if (todo == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todo);
    _context.SaveChanges();

    return NoContent();
}

Auf der Swagger-Benutzeroberfläche wird der innere Text des <summary>-Elements angezeigt, das im letzten Codeausschnitt angegeben wurde:The Swagger UI displays the inner text of the preceding code's <summary> element:

Swagger-Benutzeroberfläche mit dem XML-Kommentar „Löscht ein bestimmtes TodoItem.“

Die Benutzeroberfläche wird durch das generierte JSON-Schema gesteuert:The UI is driven by the generated JSON schema:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "operationId": "ApiTodoByIdDelete",
    "consumes": [],
    "produces": [],
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "type": "integer",
            "format": "int64"
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
}

Fügen Sie der Dokumentation der Create-Aktionsmethode ein <remarks>-Element hinzu.Add a <remarks> element to the Create action method documentation. Dieses ergänzt die Informationen, die im <summary>-Element angegeben wurden, und sorgt für eine robustere Swagger-Benutzeroberfläche.It supplements information specified in the <summary> element and provides a more robust Swagger UI. Das <remarks>-Element kann aus Text, JSON-Code oder XML-Code bestehen.The <remarks> element content can consist of text, JSON, or XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(typeof(TodoItem), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
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);
}
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

Durch die zusätzlichen Kommentare wird die Benutzeroberfläche wie unten gezeigt erweitert:Notice the UI enhancements with these additional comments:

Swagger-Benutzeroberfläche mit zusätzlichen Kommentaren

DatenanmerkungenData annotations

Markieren Sie das Modell mit Attributen aus dem Namespace System.ComponentModel.DataAnnotations, um die Komponenten der Swagger-Benutzeroberfläche zu unterstützen.Mark the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components.

Fügen Sie das [Required]-Attribut der Name-Eigenschaft der TodoItem-Klasse hinzu:Add the [Required] attribute to the Name property of the TodoItem class:

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

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }

        [Required]
        public string Name { get; set; }

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

Das Vorhandensein dieses Attributs ändert das Verhalten der Benutzeroberfläche und des zugrunde liegenden JSON-Schemas:The presence of this attribute changes the UI behavior and alters the underlying JSON schema:

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

Fügen Sie das [Produces("application/json")]-Attribut zum API-Controller hinzu.Add the [Produces("application/json")] attribute to the API controller. Dadurch kann deklariert werden, dass die Aktionen des Controllers den Inhaltstyp application/json für Antworten unterstützen:Its purpose is to declare that the controller's actions support a response content type of application/json :

[Produces("application/json")]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;
[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;
[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
    private readonly TodoContext _context;

Im Dropdownmenü des Anforderungsinhaltstyps ist dieser Inhaltstyp als Standard für die GET-Aktionen des Controllers ausgewählt:The Response Content Type drop-down selects this content type as the default for the controller's GET actions:

Swagger UI mit Standardinhaltstyp für die Antwort

Mit zunehmender Verwendung von Datenanmerkungen in der Web-API werden die UI- und API-Hilfeseiten beschreibender und nützlicher.As the usage of data annotations in the web API increases, the UI and API help pages become more descriptive and useful.

Beschreiben von AntworttypenDescribe response types

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).Developers consuming a web API are most concerned with what's returned—specifically response types and error codes (if not standard). Die Antworttypen und Fehlercodes sind in den XML-Kommentaren und Datenanmerkungen gekennzeichnet.The response types and error codes are denoted in the XML comments and data annotations.

Die Aktion Create gibt bei einer erfolgreichen Anforderung den Statuscode „HTTP 201“ zurück.The Create action returns an HTTP 201 status code on success. Der Statuscode „HTTP 400“ wird zurückgegeben, wenn der gesendete Anforderungstext NULL ist.An HTTP 400 status code is returned when the posted request body is null. Ohne richtige Dokumentation in der Swagger-Benutzeroberfläche fehlt dem Consumer das Wissen über diese erwarteten Ergebnisse.Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. Sie können dieses Problem beheben, indem Sie die hervorgehobenen Zeilen im folgenden Beispiel hinzufügen:Fix that problem by adding the highlighted lines in the following example:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>            
[HttpPost]
[ProducesResponseType(typeof(TodoItem), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
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);
}
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}
/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <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 ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

Die Swagger-Benutzeroberfläche dokumentiert nun deutlich die erwarteten HTTP-Antwortcodes:The Swagger UI now clearly documents the expected HTTP response codes:

Swagger-Benutzeroberfläche, die die Klassenbeschreibung „Gibt das neu erstellte Todo-Element zurück“ nach der Antwort anzeigt sowie „400“ für den Statuscode und „Wenn das Element NULL ist“ als Grund unter den Antwortnachrichten

In ASP.NET Core 2.2 oder höher können Konventionen als Alternative verwendet werden, um einzelne Aktionen explizit mit [ProducesResponseType] zu ergänzen.In ASP.NET Core 2.2 or later, conventions can be used as an alternative to 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.

Zur Unterstützung der [ProducesResponseType]-Ergänzung bietet das Swashbuckle.AspNetCore.Annotations-Paket Erweiterungen zum Aktivieren und Erweitern der Antwort-, Schema- und Parametermetadaten.To support the [ProducesResponseType] decoration, the Swashbuckle.AspNetCore.Annotations package offers extensions to enable and enrich the response, schema, and parameter metadata.

Anpassen der BenutzeroberflächeCustomize the UI

Die Standardbenutzeroberfläche ist zwar funktionsfähig und visuell ansprechend,The default UI is both functional and presentable. auf API-Dokumentationsseiten sollte jedoch Ihre Marke oder Ihr Design zu sehen sein.However, API documentation pages should represent your brand or theme. Für das Branding von Swashbuckle-Komponenten sind zusätzliche Ressourcen erforderlich, damit statische Dateien bereitgestellt werden können und sich die Ordnerstruktur zum Hosten dieser Dateien erstellt lässt.Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.

Wenn .NET Framework oder .NET Core 1.x die Zielkomponente ist, müssen Sie Ihrem Projekt das NuGet-Paket Microsoft.AspNetCore.StaticFiles hinzufügen:If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project:

<PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />

Dieses Paket ist bereits installiert, wenn Sie als Zielkomponente .NET Core 2.x und das Metapaket verwenden.The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.

Aktivieren von Middleware für statische Dateien:Enable Static File Middleware:

public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Um zusätzliche CSS-Stylesheets hinzuzufügen, fügen Sie sie dem Ordner wwwroot des Projekts hinzu, und geben Sie den relativen Pfad in den Middlewareoptionen an:To inject additional CSS stylesheets, add them to the project's wwwroot folder and specify the relative path in the middleware options:

app.UseSwaggerUI(c =>
{
     c.InjectStylesheet("/swagger-ui/custom.css");
}