Exercício - Use Swashbuckle para criar um documento OpenAPI

Concluído

Neste exercício, você vai adicionar o Swagger e a interface do usuário dele a um aplicativo de API Web do ASP.NET Core. As ferramentas Swagger ajudam você a criar o documento OpenAPI que descreve sua API da web.

Observação

Baixe o código-fonte no seu computador local para concluir este exercício. Após o download, é necessário descompactá-lo.

Download: aplicativo de API Web do ASP.NET Core.

1. Selecione o botão Baixar arquivo raw.
2. Descompacte o arquivo exercise.zip.

Adicionar as ferramentas do Swagger

1. Abra o Visual Studio e localize o aplicativo de API Web do ASP.NET Core.

   

2. No Gerenciador de Soluções, clique com o botão direito no projeto e escolha Gerenciar Pacotes NuGet.

   

3. No Gerenciador de Pacotes NuGet, pesquise Swashbuckle.AspNetCore. Selecione o pacote e instale-o.

   

   O pacote NuGet foi instalado. Feche a guia Gerenciador de Pacotes NuGet.

Configurar o Swashbuckle para gerar um documento OpenAPI

1. Abra o arquivo Startup.cs.

   

2. Adicione a diretiva a seguir acima da linha namespace InventoryManagement.ApiApp.

   /* === using directive BEGIN === */
   using Microsoft.OpenApi.Models;
   /* === using directive END === */
   

3. Substitua todo o código dentro do método ConfigureServices(IServiceCollection) pelo seguinte código:

       services.AddControllers();
   
       /* === SwaggerGen BEGIN === */
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
       });
       /* === SwaggerGen END === */
   

4. Dentro do método Configure(IApplicationBuilder, IWebHostEnvironment), localize a instrução condicional if (env.IsDevelopment()) e substitua tudo acima dessa instrução pelo seguinte código:

       /* === SwaggerUI BEGIN === */
       app.UseSwagger(c =>
       {
           c.PreSerializeFilters.Add((swagger, httpReq) => {
               var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
               swagger.Servers = new List<OpenApiServer>() { server };
           });
       });
       app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
       /* === SwaggerUI END === */
   

   Observação

   É muito importante que os pontos de extremidade do Swagger sejam habilitados somente no ambiente de desenvolvimento. Caso contrário, isso poderia expor sua API ao público.

   Agora você concluiu a ativação do recurso de documento OpenAPI para seu aplicativo ASP.NET Core Web API. Salve o arquivo Startup.cs. Suas alterações serão parecidas com as da captura de tela abaixo.

   

Gerar o arquivo de documento OpenAPI

1. Selecione o botão de depuração na parte de cima do Visual Studio.

   

   Ele abre automaticamente o navegador da Web e exibe a página da interface do usuário do Swagger.

   

   É possível que apareça a página de erro 404. Nesse caso, insira a URL, https://localhost:<port_number>/swagger, na barra de endereços do navegador. Na captura de tela a seguir, a URL é https://localhost:44371/swagger, por exemplo.

   

2. Selecione no link para abrir a página do documento OpenAPI.

   

3. O documento OpenAPI é renderizado rapidamente.

   

Agora, seu aplicativo de API Web do ASP.NET Core está pronto para produzir o documento OpenAPI.