Introdução ao Swashbuckle e ao ASP.NET CoreGet started with Swashbuckle and ASP.NET Core

Por Shayne Boyer e Scott AddieBy Shayne Boyer and Scott Addie

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Há três componentes principais bo Swashbuckle:There are three main components to Swashbuckle:

  • Swashbuckle.AspNetCore.Swagger: um modelo de objeto e um middleware do Swagger para expor objetos SwaggerDocument como pontos de extremidade JSON.Swashbuckle.AspNetCore.Swagger: a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.

  • Swashbuckle.AspNetCore.SwaggerGen: um gerador do Swagger cria objetos SwaggerDocument diretamente de modelos, controladores e rotas.Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers, and models. Normalmente, ele é combinado com o middleware de ponto de extremidade do Swagger para expor automaticamente o JSON do Swagger.It's typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON.

  • Swashbuckle.AspNetCore.SwaggerUI: uma versão incorporada da ferramenta de interface do usuário do Swagger.Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool. Ele interpreta o JSON do Swagger para criar uma experiência avançada e personalizável para descrever a funcionalidade da API Web.It interprets Swagger JSON to build a rich, customizable experience for describing the web API functionality. Ela inclui o agente de teste interno para os métodos públicos.It includes built-in test harnesses for the public methods.

Instalação do pacotePackage installation

O Swashbuckle pode ser adicionado com as seguintes abordagens:Swashbuckle can be added with the following approaches:

  • Da janela Console do Gerenciador de Pacotes:From the Package Manager Console window:

    • Acesse Exibição > Outras Janelas > Console do Gerenciador de PacotesGo to View > Other Windows > Package Manager Console

    • Navegue para o diretório no qual o arquivo TodoApi.csproj está localizadoNavigate to the directory in which the TodoApi.csproj file exists

    • Execute o seguinte comando:Execute the following command:

      Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc2
      
  • Da caixa de diálogo Gerenciar Pacotes NuGet:From the Manage NuGet Packages dialog:

    • Clique com o botão direito do mouse no projeto em Gerenciador de Soluções > Gerenciar Pacotes NuGetRight-click the project in Solution Explorer > Manage NuGet Packages
    • Defina a Origem do pacote para "nuget.org"Set the Package source to "nuget.org"
    • Verifique se a opção "Incluir pré-lançamento" está habilitadaEnsure the "Include prerelease" option is enabled
    • Insira "Swashbuckle.AspNetCore" na caixa de pesquisaEnter "Swashbuckle.AspNetCore" in the search box
    • Selecione o pacote "Swashbuckle.AspNetCore" mais recente na guia Procurar e clique em InstalarSelect the latest "Swashbuckle.AspNetCore" package from the Browse tab and click Install

Adicionar e configurar o middleware do SwaggerAdd and configure Swagger middleware

Na classe Startup, importe o namespace a seguir para usar a classe OpenApiInfo:In the Startup class, import the following namespace to use the OpenApiInfo class:

using Microsoft.OpenApi.Models;

Adicione o gerador do Swagger à coleção de serviços no método Startup.ConfigureServices: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(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}
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 { Title = "My API", Version = "v1" });
    });
}

No método Startup.Configure, habilite o middleware para atender ao documento JSON gerado e à interface do usuário do 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();
}

A chamada do método UseSwaggerUI precedente habilita o middleware de arquivos estáticos.The preceding UseSwaggerUI method call enables the Static File Middleware. Se você estiver direcionando ao .NET Framework ou ao .NET Core 1.x, adicione o pacote NuGet Microsoft.AspNetCore.StaticFiles ao projeto.If targeting .NET Framework or .NET Core 1.x, add the Microsoft.AspNetCore.StaticFiles NuGet package to the project.

Inicie o aplicativo e navegue até http://localhost:<port>/swagger/v1/swagger.json.Launch the app, and navigate to http://localhost:<port>/swagger/v1/swagger.json. O documento gerado que descreve os pontos de extremidade é exibido conforme é mostrado na Especificação do Swagger (swagger.json).The generated document describing the endpoints appears as shown in Swagger specification (swagger.json).

A interface do usuário do Swagger pode ser encontrada em http://localhost:<port>/swagger.The Swagger UI can be found at http://localhost:<port>/swagger. Explore a API por meio da interface do usuário do Swagger e incorpore-a em outros programas.Explore the API via Swagger UI and incorporate it in other programs.

Dica

Para atender à interface do usuário do Swagger na raiz do aplicativo (http://localhost:<port>/), defina a propriedade RoutePrefix como uma cadeia de caracteres vazia: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;
});

Se estiver usando diretórios com o IIS ou um proxy reverso, defina o ponto de extremidade do Swagger como um caminho relativo usando o prefixo ./.If using directories with IIS or a reverse proxy, set the Swagger endpoint to a relative path using the ./ prefix. Por exemplo, ./swagger/v1/swagger.json.For example, ./swagger/v1/swagger.json. Usar o /swagger/v1/swagger.json instrui o aplicativo a procurar o arquivo JSON na raiz verdadeira da URL (mais o prefixo da rota, se usado).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). Por exemplo, use http://localhost:<port>/<route_prefix>/swagger/v1/swagger.json em vez de 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.

Personalizar e estenderCustomize and extend

O Swagger fornece opções para documentar o modelo de objeto e personalizar a interface do usuário para corresponder ao seu tema.Swagger provides options for documenting the object model and customizing the UI to match your theme.

Descrição e informações da APIAPI info and description

A ação de configuração passada para o método AddSwaggerGen adiciona informações como o autor, a licença e a descrição:The configuration action passed to the AddSwaggerGen method adds information such as the author, license, and description:

// 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"),
        }
    });
});

A interface do usuário do Swagger exibe as informações da versão:The Swagger UI displays the version's information:

A interface do usuário do Swagger com informações de versão: descrição, autor e link veja mais

comentários XMLXML comments

Comentários XML podem ser habilitados com as seguintes abordagens:XML comments can be enabled with the following approaches:

  • Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Editar <nome_do_projeto>.csproj.Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • Manualmente, adicione as linhas destacadas ao arquivo .csproj:Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • Clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Propriedades.Right-click the project in Solution Explorer and select Properties.
  • Marque a caixa Arquivo de documentação XML na seção Saída da guia Build.Check the XML documentation file box under the Output section of the Build tab.

A habilitação de comentários XML fornece informações de depuração para os membros e os tipos públicos não documentados.Enabling XML comments provides debug information for undocumented public types and members. Os membros e tipos não documentados são indicados por mensagem de aviso.Undocumented types and members are indicated by the warning message. Por exemplo, a seguinte mensagem indica uma violação do código de aviso 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()'

Para suprimir os avisos de todo o projeto, defina uma lista separada por ponto e vírgula dos códigos de aviso a serem ignorados no arquivo do projeto.To suppress warnings project-wide, define a semicolon-delimited list of warning codes to ignore in the project file. Acrescentar os códigos de aviso ao $(NoWarn); também aplica os valores padrão 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>

Para suprimir avisos somente para membros específicos, coloque o código nas diretivas de pré-processador #pragma warning.To suppress warnings only for specific members, enclose the code in #pragma warning preprocessor directives. Essa abordagem é útil para o código que não deve ser exposto por meio dos documentos da API. No exemplo a seguir, o código de aviso CS1591 é ignorado para toda a classe Program.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. A imposição do código de aviso é restaurada no fechamento da definição de classe.Enforcement of the warning code is restored at the close of the class definition. Especifique vários códigos de aviso com uma lista delimitada por vírgulas.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
}

Configure o Swagger para usar o arquivo XML gerado com as instruções anteriores.Configure Swagger to use the XML file that's generated with the preceding instructions. Para sistemas operacionais Linux ou que não sejam Windows, os caminhos e nomes de arquivo podem diferenciar maiúsculas de minúsculas.For Linux or non-Windows operating systems, file names and paths can be case-sensitive. Por exemplo, um arquivo TodoApi.XML é válido no Windows, mas não no 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.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);
    });
}

No código anterior, a Reflexão é usada para criar um nome de arquivo XML correspondente ao do projeto de API Web.In the preceding code, Reflection is used to build an XML file name matching that of the web API project. A propriedade AppContext.BaseDirectory é usada para construir um caminho para o arquivo XML.The AppContext.BaseDirectory property is used to construct a path to the XML file. Alguns recursos do Swagger (como os esquemas de parâmetros de entrada ou dos métodos HTTP e os códigos de resposta dos respectivos atributos) funcionam sem o uso de um arquivo de documentação 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. Para a maioria dos recursos, ou seja, resumos de método e descrições dos parâmetros e códigos de resposta, é obrigatório o uso de um arquivo XML.For most features, namely method summaries and the descriptions of parameters and response codes, the use of an XML file is mandatory.

Adicionar comentários de barra tripla a uma ação aprimora a interface do usuário do Swagger adicionando a descrição ao cabeçalho da seção.Adding triple-slash comments to an action enhances the Swagger UI by adding the description to the section header. Adicione um elemento <summary> acima da ação Delete: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();
}

A interface do usuário do Swagger exibe o texto interno do elemento <summary> do código anterior:The Swagger UI displays the inner text of the preceding code's <summary> element:

A interface do usuário do Swagger, mostrando o comentário XML 'Exclui um TodoItem específico'.

A interface do usuário é controlada pelo esquema JSON gerado: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"
        }
    }
}

Adicione um elemento <remarks> na documentação do método da ação Create.Add a <remarks> element to the Create action method documentation. Ele complementa as informações especificadas no elemento <summary> e fornece uma interface de usuário do Swagger mais robusta.It supplements information specified in the <summary> element and provides a more robust Swagger UI. O conteúdo do elemento <remarks> pode consistir em texto, JSON ou 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), 201)]
[ProducesResponseType(400)]
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(201)]
[ProducesResponseType(400)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

Observe os aprimoramentos da interface do usuário com esses comentários adicionais:Notice the UI enhancements with these additional comments:

Interface do usuário do Swagger com comentários adicionais mostrados

Anotações de dadosData annotations

Decore o modelo com atributos, encontrados no namespace System.ComponentModel.DataAnnotations, para ajudar a gerar os componentes da interface do usuário do Swagger.Decorate the model with attributes, found in the System.ComponentModel.DataAnnotations namespace, to help drive the Swagger UI components.

Adicione o atributo [Required] à propriedade Name da classe TodoItem: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; }
    }
}

A presença desse atributo altera o comportamento da interface do usuário e altera o esquema JSON subjacente: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"
            }
        }
    }
},

Adicione o atributo [Produces("application/json")] ao controlador da API.Add the [Produces("application/json")] attribute to the API controller. Sua finalidade é declarar que as ações do controlador permitem o tipo de conteúdo de resposta application/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;

A lista suspensa Tipo de Conteúdo de Resposta seleciona esse tipo de conteúdo como o padrão para ações GET do controlador:The Response Content Type drop-down selects this content type as the default for the controller's GET actions:

Interface do usuário do Swagger com o tipo de conteúdo de resposta padrão

À medida que aumenta o uso de anotações de dados na API Web, a interface do usuário e as páginas de ajuda da API se tornam mais descritivas e úteis.As the usage of data annotations in the web API increases, the UI and API help pages become more descriptive and useful.

Descrever os tipos de respostaDescribe response types

Os desenvolvedores que usam uma API Web estão mais preocupados com o que é retornado—, especificamente, os tipos de resposta e os códigos de erro (se eles não forem padrão).Developers consuming a web API are most concerned with what's returned—specifically response types and error codes (if not standard). Os tipos de resposta e os códigos de erro são indicados nos comentários XML e nas anotações de dados.The response types and error codes are denoted in the XML comments and data annotations.

A ação Create retorna um código de status HTTP 201 em caso de sucesso.The Create action returns an HTTP 201 status code on success. Um código de status HTTP 400 é retornado quando o corpo da solicitação postada é nulo.An HTTP 400 status code is returned when the posted request body is null. Sem a documentação adequada na interface do usuário do Swagger, o consumidor não tem conhecimento desses resultados esperados.Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. Corrija esse problema adicionando as linhas realçadas no exemplo a seguir: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), 201)]
[ProducesResponseType(400)]
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(201)]
[ProducesResponseType(400)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

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

A interface do usuário do Swagger agora documenta claramente os códigos de resposta HTTP esperados:The Swagger UI now clearly documents the expected HTTP response codes:

A interface do usuário do Swagger mostra a descrição da classe de resposta POST, 'Retorna o item de tarefa pendente recém-criado' e '400 – se o item for nulo' para o código de status e o motivo em Mensagens de Resposta

No ASP.NET Core 2.2 ou posterior, as convenções podem ser usadas como uma alternativa para decorar explicitamente as ações individuais com [ProducesResponseType].In ASP.NET Core 2.2 or later, conventions can be used as an alternative to explicitly decorating individual actions with [ProducesResponseType]. Para obter mais informações, consulte Usar convenções de API Web.For more information, see Usar convenções de API Web.

Personalizar a interface do usuárioCustomize the UI

A interface do usuário de estoque é apresentável e funcional.The stock UI is both functional and presentable. No entanto, as páginas de documentação da API devem representar a sua marca ou o seu tema.However, API documentation pages should represent your brand or theme. Para inserir sua marca nos componentes do Swashbuckle é necessário adicionar recursos para atender aos arquivos estáticos e criar a estrutura de pasta para hospedar esses arquivos.Branding the Swashbuckle components requires adding the resources to serve static files and building the folder structure to host those files.

Se você estiver direcionando ao .NET Framework ou ao .NET Core 1.x, adicione o pacote do NuGet Microsoft.AspNetCore.StaticFiles ao projeto: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" />

O pacote do NuGet anterior já estará instalado se você estiver direcionando ao .NET Core 2.x e usando o metapackage.The preceding NuGet package is already installed if targeting .NET Core 2.x and using the metapackage.

Habilitar o middleware de arquivos estáticos: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();
}

Adquira o conteúdo da pasta dist do repositório GitHub da interface do usuário do Swagger.Acquire the contents of the dist folder from the Swagger UI GitHub repository. Essa pasta contém os ativos necessários para a página da interface do usuário do Swagger.This folder contains the necessary assets for the Swagger UI page.

Crie uma pasta swagger/wwwroot/ui e copie para ela o conteúdo da pasta dist.Create a wwwroot/swagger/ui folder, and copy into it the contents of the dist folder.

Crie um arquivo custom.css em swagger/wwwroot/ui, com o seguinte CSS para personalizar o cabeçalho da página:Create a custom.css file, in wwwroot/swagger/ui, with the following CSS to customize the page header:

.swagger-ui .topbar {
    background-color: #000;
    border-bottom: 3px solid #547f00;
}

Referencie custom.css no arquivo index.html depois de todos os outros arquivos CSS:Reference custom.css in the index.html file, after any other CSS files:

<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="./swagger-ui.css">
<link rel="stylesheet" type="text/css" href="custom.css">

Navegue até a página index.html em http://localhost:<port>/swagger/ui/index.html.Browse to the index.html page at http://localhost:<port>/swagger/ui/index.html. Digite http://localhost:<port>/swagger/v1/swagger.json na caixa de texto do cabeçalho e clique no botão Explorar.Enter http://localhost:<port>/swagger/v1/swagger.json in the header's textbox, and click the Explore button. A página resultante será semelhante ao seguinte:The resulting page looks as follows:

Interface do usuário do Swagger com o título do cabeçalho personalizado

Há muito mais que você pode fazer com a página.There's much more you can do with the page. Consulte as funcionalidades completas para os recursos de interface do usuário no repositório GitHub da interface do usuário do Swagger.See the full capabilities for the UI resources at the Swagger UI GitHub repository.