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.

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

    Default Swagger UI for our API.

    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

  1. Volte para a instância do Visual Studio Code que você usou no último exercício.

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

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

  4. Em Startup.cs, adicione as instruções using a seguir.

    using System.Reflection;
using System.IO;

  5. 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://learn.microsoft.com/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.

  6. 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}";
 }

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

  8. Para ver as alterações, execute o aplicativo ASP.NET localmente digitando o seguinte na janela do terminal do Visual Studio Code:

    dotnet run

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

    Swagger UI with the final documentation from XML comments for our API.

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.

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

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

  1. Adicione a seguinte instrução using ao arquivo PriceFrameController.cs.

    using Microsoft.AspNetCore.Http;

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

  3. Recompile a API Web com o seguinte comando:

    dotnet build

  4. Execute o aplicativo ASP.NET com o seguinte comando:

    dotnet run

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

    Swagger UI with more documentation from XML comments for our API.

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