Exercício – Habilitar a documentação do OpenAPI em um aplicativo de API Web ASP.NET Core

• 8 minutos

Sua empresa tem uma API chamada PrintFramerAPI que calcula o custo de uma moldura com base em suas dimensões. Internamente, sua equipe pequena sabe como usar a API. No entanto, para que a API seja adotada por terceiros e, portanto, impulsione os negócios, você precisa documentá-la. A APIT é uma API do ASP.NET Core, portanto, você decide expor a documentação da API por meio do OpenAPI.

Neste exercício, você documenta uma API Web do ASP.NET Core com o OpenAPI e experimenta a interface do usuário do Swagger e o Swashbuckle em um exemplo do mundo real. Primeiro, criaremos um projeto de API Web do ASP.NET Core.

Baixe o projeto de API Web de exemplo para o Visual Studio Code

1. Abra uma nova instância do Visual Studio Code.

2. Selecione Exibir e, em seguida, Terminal para abrir a janela do terminal.

3. (Opcional) Altere para um diretório no qual você deseja copiar os arquivos, como c:\MyProjects.

4. Para clonar o projeto de API Web de exemplo do GitHub, execute o comando git clone a seguir na janela do terminal.

   git clone https://github.com/MicrosoftDocs/mslearn-improve-api-developer-experience-with-swagger && cd mslearn-improve-api-developer-experience-with-swagger/PrintFramerAPI
   

5. Abra o projeto no Visual Studio Code com o comando de terminal a seguir.

   code -a .
   

Executar a API Web pela primeira vez

1. Digite o seguinte comando na janela do terminal do Visual Studio Code:

   dotnet run
   

2. Depois que a saída do comando for concluída, navegue até: http://localhost:5000/api/priceframe/6/17

   Quando você navegar até o endereço no navegador, ela deverá responder com a mensagem The cost of a 6x17 frame is $20.00.

Como você criou a API, sabia qual era a sua forma, mas um desenvolvedor externo que desejasse consumir essa API não teria tanta sorte. Você pode ajudar esses desenvolvedores expondo algumas documentações sobre a API com a ajuda do OpenAPI usando o Swashbuckle, uma versão de software livre das ferramentas do Swagger.

Adicionar a biblioteca de Swagger à solução

1. Adicione o Swashbuckle ao projeto executando o comando dotnet add package.

   dotnet add package Swashbuckle.AspNetCore
   

2. Abra o arquivo Startup.cs.

3. Na parte superior do arquivo, adicione outra entrada using:

   using Microsoft.OpenApi.Models;
   

4. Para adicionar o gerador do Swagger à coleção de serviços, substitua o método ConfigureServices(IServiceCollection services) pela implementação a seguir.

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllers();
   
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
       });
   }
   

5. No método Configure, em Startup.cs, habilite o middleware para a interface do usuário do Swagger adicionando useSwagger e useSwaggerUI, conforme mostrado no snippet de código a seguir.

   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
       if (env.IsDevelopment())
       {
           app.UseSwagger();
           app.UseSwaggerUI(c =>
           {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
           });
   
           app.UseDeveloperExceptionPage();
       }
   
       app.UseHttpsRedirection();
   
       app.UseRouting();
   
       app.UseAuthorization();
   
       app.UseEndpoints(endpoints =>
       {
           endpoints.MapControllers();
       }); 
   }
   

6. Salve as alterações no editor.

7. Para ver suas alterações, execute o aplicativo ASP.NET localmente. Digite o seguinte comando na janela do terminal no Visual Studio Code:

   dotnet run
   

8. Em um navegador, navegue até http://localhost:5000/swagger/v1/swagger.json.

   A resposta no navegador neste momento é um documento que descreve os pontos de extremidade da API, semelhante à resposta a seguir.