Wprowadzenie do Swashbuckle i ASP.NET CoreGet started with Swashbuckle and ASP.NET Core

Autorzy Shayne Boyer i Scott AddieBy Shayne Boyer and Scott Addie

Wyświetl lub pobierz przykładowy kod (jak pobrać)View or download sample code (how to download)

Pakiet Swashbuckle składa się z trzech głównych składników:There are three main components to Swashbuckle:

  • Swashbuckle. AspNetCore. Swagger: model obiektów Swagger i oprogramowanie pośredniczące umożliwiające Uwidacznianie SwaggerDocument obiektów jako punktów końcowych JSON.Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.

  • Swashbuckle. AspNetCore. SwaggerGen: Generator Swagger, który kompiluje SwaggerDocument obiekty bezpośrednio z tras, kontrolerów i modeli.Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models. Zazwyczaj jest ona łączona z oprogramowaniem pośredniczącym punktu końcowego programu Swagger, aby automatycznie uwidaczniać kod JSON programu Swagger.It's typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.

  • Swashbuckle. AspNetCore. SwaggerUI: wbudowana wersja narzędzia interfejsu użytkownika struktury Swagger.Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. Interpretuje kod JSON programu Swagger w celu tworzenia rozbudowanych, możliwych do dostosowania środowisk na potrzeby opisywania funkcji internetowego interfejsu API.It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. Obejmuje wbudowane kontrolery testów dla metod publicznych.It includes built-in test harnesses for the public methods.

Instalacja pakietuPackage installation

Swashbuckle można dodać przy użyciu następujących metod:Swashbuckle can be added with the following approaches:

  • W oknie konsola Menedżera pakietów :From the Package Manager Console window:

    • Przejdź do wyświetlania > innych > konsoli Menedżera pakietów systemu WindowsGo to View > Other Windows > Package Manager Console

    • Przejdź do katalogu, w którym znajduje się plik TodoApi. csprojNavigate to the directory in which the TodoApi.csproj file exists

    • Uruchom następujące polecenie:Execute the following command:

      Install-Package Swashbuckle.AspNetCore -Version 5.5.0
      
  • W oknie dialogowym Zarządzanie pakietami NuGet :From the Manage NuGet Packages dialog:

    • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań > Zarządzanie pakietami NuGetRight-click the project in Solution Explorer > Manage NuGet Packages
    • Ustaw Źródło pakietu na "NuGet.org"Set the Package source to "nuget.org"
    • Upewnij się, że opcja "Uwzględnij wersję wstępną" jest włączonaEnsure the "Include prerelease" option is enabled
    • Wprowadź ciąg "Swashbuckle. AspNetCore" w polu wyszukiwaniaEnter "Swashbuckle.AspNetCore" in the search box
    • Wybierz najnowszy pakiet "Swashbuckle. AspNetCore" z karty Przeglądaj , a następnie kliknij przycisk Instaluj .Select the latest "Swashbuckle.AspNetCore" package from the Browse tab and click Install

Dodawanie i Konfigurowanie oprogramowania pośredniczącego programu SwaggerAdd and configure Swagger middleware

Dodaj Generator Swagger do kolekcji usług w Startup.ConfigureServices metodzie: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();
}

W Startup.Configure metodzie Włącz oprogramowanie pośredniczące do obsługi wygenerowanego dokumentu JSON i interfejsu użytkownika programu Swagger: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();
    });
}

Uwaga

Swashbuckle opiera się na MVC Microsoft.AspNetCore.Mvc.ApiExplorer , aby odnaleźć trasy i punkty końcowe.Swashbuckle relies on MVC's Microsoft.AspNetCore.Mvc.ApiExplorer to discover the routes and endpoints. Jeśli wywołania projektu AddMvc , trasy i punkty końcowe są wykrywane automatycznie.If the project calls AddMvc, routes and endpoints are discovered automatically. Podczas wywoływania AddMvcCore AddApiExplorer Metoda musi być jawnie wywołana.When calling AddMvcCore, the AddApiExplorer method must be explicitly called. Aby uzyskać więcej informacji, zobacz Swashbuckle, ApiExplorer i Routing.For more information, see Swashbuckle, ApiExplorer, and Routing.

Poprzednie UseSwaggerUI wywołanie metody włącza oprogramowanie pośredniczące pliku statycznego.The preceding UseSwaggerUI method call enables the Static File Middleware. Jeśli obiektem docelowym jest .NET Framework lub .NET Core 1. x, Dodaj pakiet NuGet Microsoft. AspNetCore. StaticFiles do projektu.If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.

Uruchom aplikację i przejdź do http://localhost:<port>/swagger/v1/swagger.json .Launch the app, and navigate to http://localhost:<port>/swagger/v1/swagger.json. Wygenerowany dokument opisujący punkty końcowe wygląda tak, jak pokazano w specyfikacji openapi (openapi.json).The generated document describing the endpoints appears as shown in OpenAPI specification (openapi.json).

Interfejs użytkownika struktury Swagger można znaleźć pod adresem http://localhost:<port>/swagger .The Swagger UI can be found at http://localhost:<port>/swagger. Eksploruj interfejs API za pośrednictwem interfejsu użytkownika struktury Swagger i Uwzględnij go w innych programach.Explore the API via Swagger UI and incorporate it in other programs.

Porada

Aby obpracować interfejs użytkownika struktury Swagger w katalogu głównym aplikacji ( http://localhost:<port>/ ), ustaw RoutePrefix Właściwość na pusty ciąg: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;
});

W przypadku używania katalogów z usługami IIS lub zwrotnego serwera proxy Ustaw punkt końcowy struktury Swagger na ścieżkę względną przy użyciu ./ prefiksu.If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the ./ prefix. Na przykład ./swagger/v1/swagger.json.For example, ./swagger/v1/swagger.json. Użycie /swagger/v1/swagger.json instruuje aplikację, aby wyszukać plik JSON w prawdziwym katalogu głównym adresu URL (plus prefiks trasy, jeśli jest używany).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). Na przykład: użyj opcji http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json zamiast 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.

Uwaga

Domyślnie Swashbuckle generuje i uwidacznia kod JSON struktury Swagger w wersji 3,0 specyfikacji — oficjalnie zwanej specyfikacją openapi.By default, Swashbuckle generates and exposes Swagger JSON in version 3.0 of the specification—officially called the OpenAPI Specification. Aby zapewnić zgodność z poprzednimi wersjami, można w zamian wybrać kod JSON w formacie 2,0.To support backwards compatibility, you can opt into exposing JSON in the 2.0 format instead. Ten format 2,0 jest ważny dla integracji, takich jak Microsoft PowerShell Apps i Microsoft Flow, które obecnie obsługują OpenAPI w wersji 2,0.This 2.0 format is important for integrations such as Microsoft Power Apps and Microsoft Flow that currently support OpenAPI version 2.0. Aby wybrać format 2,0, ustaw SerializeAsV2 Właściwość w Startup.Configure :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();
    });
}

Dostosuj i rozwińCustomize and extend

Struktura Swagger zawiera opcje dokumentowania modelu obiektów i dostosowywania interfejsu użytkownika w celu dopasowania go do motywu.Swagger provides options for documenting the object model and customizing the UI to match your theme.

W Startup klasie Dodaj następujące przestrzenie nazw:In the Startup class, add the following namespaces:

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

Informacje o interfejsie API i opisAPI info and description

Akcja konfiguracji przeniesiona do AddSwaggerGen metody powoduje dodanie informacji, takich jak autor, licencja i opis:The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

W Startup klasie zaimportuj następującą przestrzeń nazw, aby użyć OpenApiInfo klasy:In the Startup class, import the following namespace to use the OpenApiInfo class:

using Microsoft.OpenApi.Models;

Korzystając z OpenApiInfo klasy, należy zmodyfikować informacje wyświetlane w interfejsie użytkownika: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"),
        }
    });
});

Interfejs użytkownika struktury Swagger wyświetla informacje o wersji:The Swagger UI displays the version's information:

Interfejs użytkownika struktury Swagger z informacjami o wersji: Description, Author i linku więcej

Komentarze XMLXML comments

Komentarze XML można włączyć przy użyciu następujących metod:XML comments can be enabled with the following approaches:

  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań a następnie wybierz polecenie edytuj <Project_Name>. csproj.Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • Ręcznie Dodaj wyróżnione wiersze do pliku csproj :Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • Kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz polecenie Właściwości.Right-click the project in Solution Explorer and select Properties.
  • Sprawdź pole plik dokumentacji XML w sekcji dane wyjściowe na karcie kompilacja .Check the XML documentation file box under the Output section of the Build tab.

Włączenie komentarzy XML zapewnia informacje debugowania dla nieudokumentowanych typów publicznych i członków.Enabling XML comments provides debug information for undocumented public types and members. Nieudokumentowane typy i elementy członkowskie są wskazywane przez komunikat ostrzegawczy.Undocumented types and members are indicated by the warning message. Na przykład następujący komunikat oznacza naruszenie kodu ostrzegawczego 1591: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()'

Aby pominąć ostrzeżenia dla całego projektu, należy zdefiniować rozdzielaną średnikami listę kodów ostrzeżeń do ignorowania w pliku projektu.To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file. Dołączanie kodów ostrzeżeń w celu $(NoWarn); zastosowania wartości domyślnych języka C# .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>

Aby pominąć ostrzeżenia tylko dla określonych elementów członkowskich, należy ująć kod w #pragma ostrzeżenia preprocesora.To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives. Takie podejście jest przydatne w przypadku kodu, który nie powinien być ujawniony za pośrednictwem dokumentacji interfejsu API. W poniższym przykładzie kod ostrzegawczy CS1591 jest ignorowany dla całej Program klasy.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. Wymuszanie kodu ostrzegawczego jest przywracane po zamknięciu definicji klasy.Enforcement of the warning code is restored at the close of the class definition. Określ wiele kodów ostrzeżeń z listą rozdzielaną przecinkami.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
}

Skonfiguruj strukturę Swagger, aby używała pliku XML, który jest generowany z poprzednimi instrukcjami.Configure Swagger to use the XML file that's generated with the preceding instructions. W przypadku systemów operacyjnych Linux lub innych niż Windows nazwy plików i ścieżki mogą być rozróżniane wielkości liter.For Linux or non-Windows operating systems, file names and paths can be case-sensitive. Na przykład plik TodoApi.XML jest prawidłowy w systemie Windows, ale nie CentOS.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);
    });
}

W poprzednim kodzie odbicie jest używane do kompilowania nazwy pliku XML pasującego do projektu interfejsu API sieci Web.In the preceding code, Reflection is used to build an XML file name matching that of the web API project. Właściwość AppContext. BaseDirectory służy do konstruowania ścieżki do pliku XML.The AppContext.BaseDirectory property is used to construct a path to the XML file. Niektóre funkcje struktury Swagger (na przykład schematu parametrów wejściowych lub metod HTTP i kodów odpowiedzi z odpowiednich atrybutów) działają bez użycia pliku dokumentacji XML.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. W przypadku większości funkcji, a mianowicie podsumowania metod i opisów parametrów i kodów odpowiedzi, użycie pliku XML jest obowiązkowe.For most features, namely method summaries and the descriptions of parameters and response codes, the use of an XML file is mandatory.

Dodawanie do akcji komentarzy z potrójnym ukośnikiem ulepsza wyniki narzędzia Swagger UI przez dodanie opisu do nagłówka sekcji.Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Dodaj <summary> element powyżej Delete akcji: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();
}

Interfejs użytkownika struktury Swagger wyświetla tekst wewnętrzny elementu poprzedniego kodu <summary> :The Swagger UI displays the inner text of the preceding code's <summary> element:

Interfejs użytkownika struktury Swagger pokazujący komentarz XML "Usuwa określony TodoItem".

Interfejs użytkownika jest oparty na wygenerowanym schemacie JSON: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"
        }
    }
}

Dodaj <remarks> element do Create dokumentacji metody akcji.Add a <remarks> element to the Create action method documentation. Uzupełnia on informacje określone w <summary> elemencie i zapewnia bardziej niezawodny interfejs użytkownika struktury Swagger.It supplements information specified in the <summary> element and provides a more robust Swagger UI. <remarks>Zawartość elementu może składać się z tekstu, JSON lub XML.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);
}

Zwróć uwagę na ulepszenia interfejsu użytkownika z następującymi dodatkowymi komentarzami:Notice the UI enhancements with these additional comments:

Interfejs użytkownika struktury Swagger z pokazanymi dodatkowymi komentarzami

Adnotacje danychData annotations

Oznacz model atrybutami, które znajdują się w przestrzeni nazw System. ComponentModel. DataAnnotations , aby ułatwić DYSKOM interfejsu użytkownika struktury Swagger.Mark the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components.

Dodaj [Required] atrybut do Name właściwości TodoItem klasy: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; }
    }
}

Obecność tego atrybutu zmienia zachowanie interfejsu użytkownika i zmienia źródłowy schemat JSON: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"
            }
        }
    }
},

Dodaj [Produces("application/json")] atrybut do kontrolera interfejsu API.Add the [Produces("application/json")] attribute to the API controller. Celem jest zadeklarowanie, że działania kontrolera obsługują typ zawartości odpowiedzi dla aplikacji/JSON: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;

Lista rozwijana Typ zawartości odpowiedzi wybiera ten typ zawartości jako domyślny dla akcji Get kontrolera:The Response Content Type drop-down selects this content type as the default for the controller's GET actions:

Interfejs użytkownika struktury Swagger z domyślnym typem zawartości odpowiedzi

W miarę wzrostu użycia adnotacji danych w interfejsie API sieci Web strony interfejsu użytkownika i interfejsu API stają się bardziej opisowe i przydatne.As the usage of data annotations in the web API increases, the UI and API help pages become more descriptive and useful.

Opisz typy odpowiedziDescribe response types

Deweloperzy korzystający z internetowego interfejsu API są najbardziej zainteresowani, które są zwracane w — szczególności typy odpowiedzi i kody błędów (jeśli nie są standardem).Developers consuming a web API are most concerned with what's returned—specifically response types and error codes (if not standard). Typy odpowiedzi i kody błędów są oznaczane w komentarzach XML i adnotacjach danych.The response types and error codes are denoted in the XML comments and data annotations.

CreateAkcja zwraca kod stanu HTTP 201 na sukcesie.The Create action returns an HTTP 201 status code on success. Kod stanu HTTP 400 jest zwracany, gdy treść ogłoszonego żądania ma wartość null.An HTTP 400 status code is returned when the posted request body is null. Bez odpowiedniej dokumentacji w interfejsie użytkownika programu Swagger klient nie ma wiedzy na temat oczekiwanych wyników.Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. Rozwiąż ten problem, dodając wyróżnione wiersze w następującym przykładzie: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);
}

Interfejs użytkownika struktury Swagger teraz jasno dokumentuje oczekiwane kody odpowiedzi HTTP:The Swagger UI now clearly documents the expected HTTP response codes:

Interfejs użytkownika struktury Swagger pokazujący opis klasy odpowiedzi "zwraca nowo utworzony element zadania" i "400-Jeśli element ma wartość null" dla kodu stanu i przyczyny w komunikatach odpowiedzi

W ASP.NET Core 2,2 lub nowszych Konwencji mogą służyć jako alternatywa dla jawnego dekorowania nazwy poszczególnych akcji z [ProducesResponseType] .In ASP.NET Core 2.2 or later, conventions can be used as an alternative to explicitly decorating individual actions with [ProducesResponseType]. Aby uzyskać więcej informacji, zobacz Korzystanie z Konwencji interfejsu API sieci Web.For more information, see Korzystanie z Konwencji interfejsu API sieci Web.

Aby można było obsłużyć [ProducesResponseType] dekorację, pakiet Swashbuckle. AspNetCore. Annotations oferuje rozszerzenia umożliwiające włączenie i wzbogacenie metadanych odpowiedzi, schematu i parametru.To support the [ProducesResponseType] decoration, the Swashbuckle.AspNetCore.Annotations package offers extensions to enable and enrich the response, schema, and parameter metadata.

Dostosowywanie interfejsu użytkownikaCustomize the UI

Domyślny interfejs użytkownika jest zarówno funkcjonalny, jak i najbardziej do wysłania.The default UI is both functional and presentable. Jednak strony dokumentacji interfejsu API powinny reprezentować swoją markę lub motyw.However, API documentation pages should represent your brand or theme. Znakowanie składników Swashbuckle wymaga dodania zasobów do obsługi plików statycznych i skompilowania struktury folderów do hostowania tych plików.Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.

Jeśli obiektem docelowym jest .NET Framework lub .NET Core 1. x, Dodaj pakiet NuGet Microsoft. AspNetCore. StaticFiles do projektu: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" />

Poprzedni pakiet NuGet jest już zainstalowany, jeśli celem jest .NET Core 2. x i używanie pakietu.The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.

Włącz oprogramowanie pośredniczące plików statycznych: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();
    });
}

Aby wstrzyknąć dodatkowe arkusze stylów CSS, Dodaj je do folderu wwwroot projektu i określ ścieżkę względną w opcjach oprogramowania pośredniczącego: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");
}