Introdução ao Swashbuckle e ao ASP.NET Core

Observação

Swashbuckle não está disponível no .NET 9 e posterior. Para obter uma alternativa, consulte Visão geral do suporte a OpenAPI em aplicativos de API ASP.NET Core.

Existem três componentes principais para o Swashbuckle:

• Swashbuckle.AspNetCore.Swagger: um modelo de objetos Swagger e middleware para expor objetos SwaggerDocument como endpoints JSON.

• Swashbuckle.AspNetCore.SwaggerGen: um gerador Swagger que constrói SwaggerDocument objetos diretamente das suas rotas, controladores e modelos. Normalmente é combinado com o middleware de endpoint Swagger para expor automaticamente o Swagger JSON.

• Swashbuckle.AspNetCore.SwaggerUI: uma versão incorporada da ferramenta Swagger UI. Ele interpreta o Swagger JSON para criar uma experiência rica e personalizável para descrever a funcionalidade da API da Web. Inclui frameworks de teste incorporados para os métodos públicos.

Instalação do pacote

Swashbuckle pode ser adicionado com as seguintes abordagens:

Visual Studio

• Na janela Console do Gerenciador de Pacotes:

  • Vá para Exibir>outro console do Gerenciador de Pacotes do Windows>

  • Navegue até o diretório no qual o arquivo .csproj existe

  • Execute o seguinte comando:

    Install-Package Swashbuckle.AspNetCore -Version 6.6.2
    

• Na caixa de diálogo Gerenciar Pacotes NuGet:

  • Clique com o botão direito do mouse no projeto no Gerenciador de Soluções >Gerenciar Pacotes NuGet
  • Defina o de origem do pacote como "nuget.org"
  • Verifique se a opção "Incluir pré-lançamento" está ativada
  • Digite "Swashbuckle.AspNetCore" na caixa de pesquisa
  • Selecione o pacote "Swashbuckle.AspNetCore" mais recente no separador Procurar e clique em Instalar

Visual Studio para Mac

• Clique com o botão direito do rato na pasta Pacotes no Painel da Solução >Adicionar Pacotes...
• Defina a lista suspensa Adicionar pacotes de origem da janela como "nuget.org"
• Verifique se a opção "Mostrar pacotes de pré-lançamento" está ativada
• Digite "Swashbuckle.AspNetCore" na caixa de pesquisa
• Selecione o pacote "Swashbuckle.AspNetCore" mais recente no painel de resultados e clique em Adicionar pacote

Execute o seguinte comando a partir do Terminal Integrado:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

Execute o seguinte comando:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.6.2

Adicionar e configurar middleware Swagger

Adicione o gerador Swagger à coleção de serviços em Program.cs:

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

A chamada para AddEndpointsApiExplorer apresentada no exemplo anterior é necessária apenas para APIs mínimas. Para obter mais informações, consulte este post do StackOverflow.

Habilite o middleware para servir o documento JSON gerado e a interface Swagger, incluindo em Program.cs:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

O código anterior adiciona o middleware Swagger somente se o ambiente atual estiver definido como Desenvolvimento. A chamada do método UseSwaggerUI habilita uma versão incorporada da ferramenta Swagger UI.

Inicie o aplicativo e navegue até https://localhost:<port>/swagger/v1/swagger.json. O documento gerado descrevendo os pontos finais aparece como mostrado na especificação OpenAPI (openapi.json).

A interface do usuário do Swagger pode ser encontrada em https://localhost:<port>/swagger. Explore a API via Swagger UI e incorpore-a em outros programas.

Dica

Para servir a interface do Swagger na raiz do aplicativo (https://localhost:<port>/), defina a propriedade RoutePrefix como uma string vazia.

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

Se estiver a utilizar diretórios com o IIS ou um proxy reverso, defina o endpoint do Swagger como um caminho relativo usando o prefixo ./. Por exemplo, ./swagger/v1/swagger.json. O uso do /swagger/v1/swagger.json instrui o aplicativo a procurar o arquivo JSON na raiz verdadeira da URL (mais o prefixo da rota, se usado). Por exemplo, use https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json em vez de https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Observação

Por padrão, o Swashbuckle gera e expõe o Swagger JSON na versão 3.0 da especificação — oficialmente chamada de Especificação OpenAPI. Para oferecer suporte à compatibilidade com versões anteriores, você pode optar por expor JSON no formato 2.0. Esse formato 2.0 é importante para integrações como Microsoft Power Apps e Microsoft Flow que atualmente suportam OpenAPI versão 2.0. Para optar pelo formato 2.0, defina a propriedade SerializeAsV2 em Program.cs:

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Personalizar e estender

O Swagger fornece opções para documentar o modelo de objeto e personalizar a interface do usuário para corresponder ao seu tema.

Informações e descrição da API

A ação de configuração passada para o método AddSwaggerGen adiciona informações como autor, licença e descrição.

No Program.cs, importe o namespace a seguir para usar a classe OpenApiInfo:

using Microsoft.OpenApi.Models;

Usando a classe OpenApiInfo, modifique as informações exibidas na interface do usuário:

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

A interface do usuário do Swagger exibe as informações da versão:

Comentários XML

Os comentários XML podem ser habilitados com as seguintes abordagens:

Visual Studio

• Clique com o botão direito do mouse no projeto em Gerenciador de Soluções e selecione Edit <project_name>.csproj.
• Adicione GenerateDocumentationFile ao ficheiro .csproj:

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

Visual Studio para Mac

• No Solution Pad, pressione de controle e clique no nome do projeto. Navegue até Ferramentas >Editar arquivo.
• Adicione GenerateDocumentationFile ao ficheiro .csproj:

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

Adicione GenerateDocumentationFile ao ficheiro .csproj:

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

Adicione GenerateDocumentationFile ao ficheiro .csproj:

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

Ao ativar comentários XML, são fornecidas informações de depuração para tipos e membros públicos não documentados. Tipos e membros não documentados são indicados pela mensagem de aviso. Por exemplo, a seguinte mensagem indica uma violação do código de aviso 1591:

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

Para suprimir avisos em todo o projeto, defina uma lista delimitada por ponto-e-vírgula de códigos de aviso a serem ignorados no arquivo de projeto. Anexar os códigos de aviso a $(NoWarn); também aplica os valores padrão de C# .

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

Para suprimir avisos apenas para membros específicos, coloque o código em diretivas de pré-processador #pragma warning. Essa abordagem é útil para 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 TodoContext. A aplicação do código de aviso é restaurada na conclusão da definição da classe. Especifique vários códigos de aviso com uma lista delimitada por vírgula.

namespace SwashbuckleSample.Models;

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

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

Configure o Swagger para usar o arquivo XML gerado com as instruções anteriores. Para sistemas operativos Linux ou não-Windows, os nomes de ficheiro e caminhos podem ser sensíveis a maiúsculas e minúsculas. Por exemplo, um arquivo TodoApi.XML é válido no Windows, mas não no Ubuntu.

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

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

No código anterior, Reflection é usado para criar um nome de arquivo XML correspondente ao do projeto de API da Web. A propriedade AppContext.BaseDirectory é usada para construir um caminho para o arquivo XML. Alguns recursos do Swagger (por exemplo, esquemas de parâmetros de entrada ou métodos HTTP e códigos de resposta dos respetivos atributos) funcionam sem o uso de um arquivo de documentação XML. Para a maioria dos recursos, ou seja, resumos de métodos e descrições de parâmetros e códigos de resposta, o uso de um arquivo XML é obrigatório.

Adicionar comentários de barra tripla a uma ação melhora o Swagger UI ao adicionar a descrição ao cabeçalho da secção. Adicione um elemento de resumo <> acima da ação Delete:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

A interface do usuário do Swagger exibe o texto interno do elemento <summary> do código anterior:

A interface do usuário é orientada pelo esquema JSON gerado:

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

Adicione um <elemento de observações> à documentação do método de ação Create. Ele complementa as informações especificadas no elemento <summary> e fornece uma interface do usuário Swagger mais robusta. O conteúdo do elemento <remarks> pode consistir em texto, JSON ou XML.

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

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

Observe os aprimoramentos da interface do usuário com estes comentários adicionais:

Anotações de dados

Marque o modelo com atributos, encontrados no namespace System.ComponentModel.DataAnnotations, para ajudar a conduzir os componentes da interface do usuário do Swagger.

Adicione o atributo [Required] à propriedade Name da classe TodoItem:

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

namespace SwashbuckleSample.Models;

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

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

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

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

Adicione o atributo [Produces("application/json")] ao controlador de API. O seu objetivo é declarar que as ações do controlador suportam um tipo de conteúdo de resposta do application/json:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

A lista suspensa Tipo de mídia seleciona esse tipo de conteúdo como padrão para as ações GET do controlador:

À medida que o uso de anotações de dados na API da Web aumenta, a interface do usuário e as páginas de ajuda da API se tornam mais descritivas e úteis.

Descrever os tipos de resposta

Os desenvolvedores que consomem uma API da Web estão mais preocupados com o que é retornado — especificamente tipos de resposta e códigos de erro (se não padrão). Os tipos de resposta e códigos de erro são indicados nos comentários XML e anotações de dados.

A ação Create retorna um código de status HTTP 201 com êxito. Um código de status HTTP 400 é retornado quando o corpo da solicitação postada é nulo. Sem a documentação adequada na interface do usuário do Swagger, o consumidor não tem conhecimento desses resultados esperados. Corrija esse problema adicionando as linhas realçadas no exemplo a seguir:

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

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

A interface do usuário do Swagger agora documenta claramente os códigos de resposta HTTP esperados:

As convenções podem ser usadas como uma alternativa para decorar explicitamente ações individuais com [ProducesResponseType]. Para obter mais informações, consulte Usar convenções de API da Web.

Para dar suporte à decoração [ProducesResponseType], o pacote Swashbuckle.AspNetCore.Annotations oferece extensões para habilitar e enriquecer os metadados de resposta, esquema e parâmetro.

Personalizar a interface do usuário

A interface do usuário padrão é funcional e apresentável. No entanto, as páginas de documentação da API devem representar sua marca ou tema. A identidade visual dos componentes do Swashbuckle requer a adição de recursos para servir arquivos estáticos e a construção da estrutura de pastas para hospedar esses arquivos.

Ative o middleware de ficheiro estático:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Para injetar folhas de estilo CSS adicionais, adicione-as à pasta de wwwroot do projeto e especifique o caminho relativo nas opções de middleware:

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Recursos adicionais

• Exibir ou baixar código de exemplo (como baixar)
• Melhorar a experiência do desenvolvedor de uma API com a documentação do Swagger