Exercício – Personalizar e estender a documentação do OpenAPI com comentários XML e anotações

12 minutos

Neste exercício, você enriquece a documentação que um desenvolvedor vê sobre a API adicionando comentários e anotações ao código. Primeiro, vejamos o que obtemos da interface do usuário do Swagger por padrão.

Para examinar a definição do OpenAPI do ponto de extremidade da nossa API na interface do usuário do Swagger, navegue até http://localhost:5000/swagger no navegador. Você verá uma saída semelhante à mostrada a seguir ao selecionar o método Get.

A interface do usuário do Swagger fornece algumas informações úteis sobre a API. Ela mostra os métodos que você pode chamar (no nosso caso simples, um método chamado PriceFrame). Você pode ver que é uma operação get HTTP que usa dois parâmetros obrigatórios chamados Altura e Largura. Para ver a chamada à API em ação, você pode selecionar Experimentar, inserir os valores de Altura e Largura e selecionar Executar.

Talvez os usuários da API ainda não tenham informações suficientes sobre as limitações do método PriceFrame. Vamos ajudá-los com algumas informações mais detalhadas por meio de comentários XML.

Adicionar comentários XML à sua API

Volte para a instância do Visual Studio Code que você usou no último exercício.
Se a API Web estiver em execução desde o último exercício, pressione ctrl+c no Windows ou cmd+c no Mac para interrompê-la.
Para ativar a documentação XML no projeto, atualize o arquivo de projeto PrintFramerAPI.csproj, adicione a marca GenerateDocumentationFile ao <PropertyGroup> existente e defina como true.
```
<PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
```
Em Startup.cs, adicione as instruções using a seguir.
```
using System.Reflection;
using System.IO;
```

Em seguida, vá até Startup.cs e atualize a chamada a AddSwaggerGen() em ConfigureServices para informar ao Swashbuckle para usar a documentação XML.

 public void ConfigureServices(IServiceCollection services)
 {
     services.AddControllers();

     // Register the Swagger generator, defining 1 or more Swagger documents
     services.AddSwaggerGen(c =>
     {
         c.SwaggerDoc("v1", new OpenApiInfo
         {
             Version = "v1",
             Title = "PrintFramer API",
             Description = "Calculates the cost of a picture frame based on its dimensions.",
             TermsOfService = new Uri("https://go.microsoft.com/fwlink/?LinkID=206977"),
             Contact = new OpenApiContact
             {
                 Name = "Your name",
                 Email = string.Empty,
                 Url = new Uri("https://zcusa.951200.xyz/training")
             }
         });

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

No código anterior, a reflexão determina o nome do arquivo XML no qual carregar os comentários XML.

Na pasta Controladores, abra PriceFrameController.cs. Adicione o seguinte bloco de comentário XML acima do atributo HttpGet do método GetPrice. 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.

 /// <summary>
 /// Returns the price of a frame based on its dimensions.
 /// </summary>
 /// <param name="Height">The height of the frame.</param>
 /// <param name="Width">The width of the frame.</param>
 /// <returns>The price, in dollars, of the picture frame.</returns>
 /// <remarks> The API returns 'not valid' if the total length of frame material needed (the perimeter of the frame) is less than 20 inches and greater than 1000 inches.</remarks>
 [HttpGet("{Height}/{Width}")]
 public string GetPrice(string Height, string Width)
 {
     string result;
     result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
     return $"The cost of a {Height}x{Width} frame is ${result}";
 }

Para salvar todas as alterações e ter certeza de que elas serão compiladas localmente, execute o comando a seguir na janela do terminal do Visual Studio Code.
```
dotnet build
```
Para ver as alterações, execute o aplicativo ASP.NET localmente digitando o seguinte na janela do terminal do Visual Studio Code:
```
dotnet run
```
Examine a interface do usuário do Swagger novamente em http://localhost:5000/swagger e observe as informações adicionadas fornecidas pelos seus comentários XML para a documentação do OpenAPI.

Adicionar anotações de dados à sua API

Para permitir que o Swagger melhore a documentação do OpenAPI, use atributos do namespace Microsoft.AspNetCore.Mvc.

Se a API Web estiver em execução desde o último exercício, pressione ctrl+c no Windows ou cmd+c no Mac para interrompê-la.
Para mostrar que sua API GetPrice dá suporte a uma resposta de tipo de conteúdo para text/plain, no controlador de API, PriceFrameController.cs, adicione um atributo [Produces("text/plain")] acima da definição GetPrice.
```
[HttpGet("{Height}/{Width}")]
[Produces("text/plain")]
```
A lista suspensa Tipo de Conteúdo de Resposta seleciona esse tipo de conteúdo como o padrão para as ações GET do controlador.

Adicionar anotações do Swashbuckle à sua API

Até agora, a API retorna o código de status 200, quando pode calcular o preço das dimensões de quadro fornecidas. Na descrição do método GetPrice, observe o caso em que um preço não pode ser calculado.

Uma forma mais robusta de informar aos desenvolvedores os tipos de resposta e os códigos de erro é por meio dos comentários XML e das anotações de dados a seguir. Swashbuckle e as ferramentas Swagger usam esses valores para gerar claramente uma descrição OpenAPI dos códigos de resposta HTTP esperados.

Atualize também o construtor do filtro de verbo HTTP para incluir a propriedade Name e incluir o valor OpenAPI operationId.

Adicione a seguinte instrução using ao arquivo PriceFrameController.cs.
```
using Microsoft.AspNetCore.Http;
```

Em PriceFrameController.cs, substitua GetPrice pelo código e pelo comentário a seguir.

/// <summary>
/// Returns the price of a frame based on its dimensions.
/// </summary>
/// <param name="Height">The height of the frame.</param>
/// <param name="Width">The width of the frame.</param>
/// <returns>The price, in dollars, of the picture frame.</returns>
/// <remarks>
/// Sample request:
///
///     Get /api/priceframe/5/10
///
/// </remarks>
/// <response code="200">Returns the cost of the frame in dollars.</response>
/// <response code="400">If the amount of frame material needed is less than 20 inches or greater than 1000 inches.</response>
[HttpGet("{Height}/{Width}", Name=nameof(GetPrice))]
[Produces("text/plain")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<string> GetPrice(string Height, string Width)
{
    string result;
    result = CalculatePrice(Double.Parse(Height), Double.Parse(Width));
    if (result == "not valid")
    {
        return BadRequest(result);
    }
    else
    {
        return Ok($"The cost of a {Height}x{Width} frame is ${result}");
    }
}

Essa atualização de código faz as seguintes alterações:

O método usa os métodos BadRequest() e Ok() para criar uma solicitação inválida (400) e um status OK, respectivamente, passando o resultado da cadeia de caracteres para a resposta.
Os comentários XML descrevem cada código de status que esse método pode retornar.
O atributo HttpGet inclui uma propriedade Name para emitir o parâmetro OpenAPI operationId.
Os atributos ProducesResponseType listam as diferentes respostas que a ação pode retornar. Esses atributos são combinados com comentários XML, conforme descrito anteriormente, para incluir descrições amigáveis para humanos com cada resposta no Swagger gerado

Recompile a API Web com o seguinte comando:
```
dotnet build
```
Execute o aplicativo ASP.NET com o seguinte comando:
```
dotnet run
```
Examine a interface do usuário do Swagger novamente em http://localhost:5000/swagger e observe as informações adicionadas fornecidas por essas anotações. A interface do usuário final do Swagger para a API é exibida na imagem a seguir.

Neste exercício, você enriqueceu as informações que um desenvolvedor recebe sobre a API, tornando-a muito mais fácil de ser consumida.

Exercício – Personalizar e estender a documentação do OpenAPI com comentários XML e anotações

Adicionar comentários XML à sua API

Adicionar anotações de dados à sua API

Adicionar anotações do Swashbuckle à sua API

Comentários