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

Por Christoph Nienaber, Rico Suter e Dave Brock

Exibir ou baixar código de exemplo (como baixar)

NSwag oferece os seguintes recursos:

• A capacidade de utilizar a interface do usuário do Swagger e o gerador do Swagger.
• Recursos flexíveis de geração de código.

Com o NSwag, você não precisa de uma API existente, pois pode usar APIs de terceiros que incorporam o Swagger e geram uma implementação de cliente. O NSwag permite acelerar o ciclo de desenvolvimento e adaptar-se facilmente às alterações na API.

Instalação do pacote

Instale o NSwag para:

• Gerar a especificação do Swagger para a API Web implementada.
• Oferecer a interface do usuário do Swagger para navegar e testar a API Web.
• Oferecer o Redoc para adicionar a documentação da API para a API Web.

Para usar o middleware ASP.NET Core do NSwag, instale o pacote do NuGet NSwag.AspNetCore. Este pacote contém o middleware para gerar e oferecer a especificação do Swagger, interface do usuário do Swagger (v2 e v3) e a interface do usuário do ReDoc.

Use uma das seguintes abordagens para instalar o pacote do NuGet do NSwag:

Visual Studio

• Da janela Console do Gerenciador de Pacotes:

  • Acesse Exibição>Outras Janelas>Console do Gerenciador de Pacotes

  • Navegue para o diretório no qual o arquivo NSwagSample.csproj está localizado

  • Execute o comando a seguir:

    Install-Package NSwag.AspNetCore
    

• Da caixa de diálogo Gerenciar Pacotes NuGet:

  • Clique com o botão direito do mouse no projeto em Gerenciador de Soluções>Gerenciar Pacotes NuGet
  • Defina a Origem do pacote para "nuget.org"
  • Insira "NSwag.AspNetCore" na caixa de pesquisa
  • Selecione o pacote "NSwag.AspNetCore" na guia Procurar e clique em Instalar

Visual Studio para Mac

• Clique com o botão direito do mouse na pasta Pacotes em Painel de Soluções>Adicionar Pacotes...
• Defina a lista suspensa Origem da janela Adicionar Pacotes para "nuget.org"
• Insira "NSwag.AspNetCore" na caixa de pesquisa
• Selecione o pacote "NSwag.AspNetCore" no painel de resultados e clique em Adicionar Pacote

Visual Studio Code

Execute o comando a seguir do Terminal Integrado:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

CLI do .NET Core

Execute o seguinte comando:

dotnet add NSwagSample.csproj package NSwag.AspNetCore

Adicionar e configurar o middleware do Swagger

Realize estas etapas para adicionar e configurar o Swagger em seu aplicativo ASP.NET Core:

• Adicione o gerador do OpenApi à coleção de serviços no Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApiDocument();

• Habilite o middleware para atender à especificação do OpenApi gerado, à interface do usuário do Swagger UI e a interface do usuário do Redoc, também no Program.cs:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi();
}

• Inicie o aplicativo. Navegue até:
  • http://localhost:<port>/swagger para exibir a interface do usuário do Swagger.
  • http://localhost:<port>/swagger/v1/swagger.json para exibir a especificação do Swagger.

Geração de código

Você pode tirar proveito dos recursos de geração de código do NSwag, escolhendo uma das opções a seguir:

• NSwagStudio: um aplicativo de desktop do Windows para geração do código do cliente da API em C# ou TypeScript.
• Pacotes NuGet NSwag.CodeGeneration.CSharp ou NSwag.CodeGeneration.TypeScript para a geração de código dentro do seu projeto.
• NSwag na linha de comando.
• O pacote NuGet NSwag.MSBuild.
• O Serviço Conectado do Unchase OpenAPI (Swagger): um Serviço Conectado do Visual Studio para a geração de código do cliente de API em C# ou em TypeScript. Também gera controladores C# para serviços de OpenAPI com o NSwag.

Gerar o código com NSwagStudio

• Instale o NSwagStudio, seguindo as instruções no repositório GitHub do NSwagStudio. Na página de versão do NSwag, você pode fazer o download de uma versão xcopy que pode ser iniciada sem privilégios de instalação e administrador.
• Inicie o NSwagStudio e insira a URL do arquivo swagger.json na caixa de texto URL de Especificação do Swagger. Por exemplo, http://localhost:5232/swagger/v1/swagger.json.
• Clique no botão Criar cópia local para gerar uma representação JSON de sua especificação do Swagger.

• Na área Saídas, marque a caixa de seleção Cliente CSharp. Dependendo do seu projeto, você também pode escolher Cliente TypeScript ou Controlador da API Web CSharp. Se você selecionar Controlador da API Web do CSharp, uma especificação de serviço recompilará o serviço, que servirá como uma geração inversa.
• Clique em Gerar Saídas para produzir uma implementação completa de cliente em C# do projeto TodoApi.NSwag. Para ver o código de cliente gerado, clique na guia Cliente do CSharp:

namespace MyNamespace
{
    using System = global::System;

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "14.0.1.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
    public partial class TodoClient
    {
    #pragma warning disable 8618 // Set by constructor via BaseUrl property
        private string _baseUrl;
    #pragma warning restore 8618 // Set by constructor via BaseUrl property
        private System.Net.Http.HttpClient _httpClient;
        private static System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(CreateSerializerSettings, true);

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            BaseUrl = "http://localhost:5232";
            _httpClient = httpClient;
        }

        private static Newtonsoft.Json.JsonSerializerSettings CreateSerializerSettings()
        {
            var settings = new Newtonsoft.Json.JsonSerializerSettings();
            UpdateJsonSerializerSettings(settings);
            return settings;
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set
            {
                _baseUrl = value;
                if (!string.IsNullOrEmpty(_baseUrl) && !_baseUrl.EndsWith("/"))
                    _baseUrl += '/';
            }
        }
        // code omitted for brevity

Dica

O código do cliente C# é gerado com base em seleções na guia Configurações. Modifique as configurações para executar tarefas como renomenclatura de namespace padrão e geração de método síncrono.

• Copie o código C# gerado em um arquivo no projeto do cliente que consumirá a API.
• Inicie o consumo da API Web:

var todoClient = new TodoClient(new HttpClient());

// Gets all to-dos from the API
var allTodos = await todoClient.GetAsync();

// Create a new TodoItem, and save it via the API.
await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

Personalizar a documentação da API

O OpenApi fornece opções para documentar o modelo de objeto para facilitar o consumo da API Web.

Descrição e informações da API

Em Program.cs, atualize AddOpenApiDocument para configurar as informações do documento da API Web e incluir mais informações, como o autor, a licença e a descrição. Primeiro importe o namespace NSwag para usar as classes OpenApi.

using NSwag;

var builder = WebApplication.CreateBuilder(args);

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

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

comentários XML

Para habilitar os comentários XML, execute as seguintes etapas:

Visual Studio

• Clique com o botão direito do mouse no projeto em Gerenciador de Soluções e selecione Edit <project_name>.csproj.
• Adicione manualmente as linhas realçadas ao arquivo .csproj:

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

Visual Studio para Mac

• No Painel de Soluções, pressione control e clique no nome do projeto. Navegue até Ferramentas>Editar arquivo.
• Adicione manualmente as linhas realçadas ao arquivo .csproj:

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

Visual Studio Code

Adicione manualmente as linhas realçadas ao arquivo .csproj:

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

CLI do .NET Core

Adicione manualmente as linhas realçadas ao arquivo .csproj:

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

A habilitação de comentários XML fornece informações de depuração para os membros e os tipos públicos não documentados. Os membros e tipos não documentados são indicados por 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 'TodoContext'

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. Acrescentar os códigos de aviso ao $(NoWarn); também aplica os valores padrão C#.

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

Para suprimir avisos somente para membros específicos, coloque o código nas 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 imposição do código de aviso é restaurada no fechamento da definição de classe. Especifique vários códigos de aviso com uma lista delimitada por vírgulas.

namespace NSwagSample.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

Anotações de dados

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

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

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

namespace NSwagSample.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:

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

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

Descrever os tipos de resposta

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

A ação Create retorna um código de status HTTP 201 em caso de sucesso. Um código de status HTTP 400 é retornado quando o corpo da solicitação postada é null. 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 (e os comentários XML também são exibidos):

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

Redoc

O Redoc é uma alternativa à interface do usuário do Swagger. É semelhante porque também disponibiliza uma página de documentação para a API Web usando a especificação OpenAPI. A diferença é que a interface do usuário do Redoc está mais focada na documentação e não fornece uma interface do usuário interativa para testar a API.

Para habilitar o Redoc, adicione seu middleware no Program.cs:

if (app.Environment.IsDevelopment())
{
    // Add OpenAPI 3.0 document serving middleware
    // Available at: http://localhost:<port>/swagger/v1/swagger.json
    app.UseOpenApi();

    // Add web UIs to interact with the document
    // Available at: http://localhost:<port>/swagger
    app.UseSwaggerUi();
    
    // Add ReDoc UI to interact with the document
    // Available at: http://localhost:<port>/redoc
    app.UseReDoc(options =>
    {
        options.Path = "/redoc";
    });
}

Execute o aplicativo e navegue até http://localhost:<port>/redoc para visualizar a interface do usuário do Redoc: