Enriquecer a documentação do OpenAPI com comentários XML e anotações

Concluído

A interface do usuário Swagger permite que você interaja e visualize os recursos de uma API sem requerer acesso ao código-fonte. A representação gráfica da sua API é gerada automaticamente com base na sua especificação do OpenAPI e facilita a criação de aplicativos que consomem suas APIs por outros desenvolvedores.

A interface do usuário do Swagger visualiza as operações e os métodos com clareza, conforme mostrado na imagem a seguir.

A interface do usuário do Swagger também permite interagir e até mesmo experimentar cada operação.

Criar automaticamente sua documentação de API com as ferramentas do Swashbuckle e Swagger poderá ajudar terceiros a entender os recursos da API. E no caso de você querer ir além e fornecer informações ainda mais detalhadas? Se você está usando uma API pela primeira vez, você deseja o máximo possível de informações.

Comentários XML

Você pode criar a documentação do seu código incluindo comentários XML. Normalmente, você colocaria esses comentários diretamente antes do bloco de código sobre o qual você está comentando.

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

Aqui estão os nós XML em uso:

• summary: Um resumo de alto nível do que o método/classe/campo é ou faz.
• comentários: mais detalhes sobre o método/classe/campo.
• param: Um parâmetro para o método e o que ele representa.
• returns: Uma descrição do que o método retorna.

Depois que você habilitar os comentários XML, as ferramentas do Swashbuckle poderão incluir os comentários da documentação XML na documentação da OpenAPI e permitir que você a visualize na interface do usuário do Swagger.

Anotações de dados

É o mesmo com anotações de dados. Basta adicionar uma anotação ao seu modelo, e o Swagger estende a documentação da API para incluí-la.

Por exemplo, se você adicionar a anotação a seguir a um controlador:

[Produces("application/json")]

... você verá as informações adicionadas na interface do usuário do Swagger:

Dicas

Há várias anotações de dados que você deve usar ao descrever sua API.

• Identifique qual content-types sua API trata em solicitações e respostas. Os atributos a seguir especificam que a API só deve usar o tipo de conteúdo application/json em ambas as direções.

  [Produces("application/json")]
  [Consumes("application/json")]
  

• Identifique os códigos de resposta HTTP potenciais que podem ser retornados para o cliente de chamada. O atributo a seguir ilustra uma API que pode retornar um erro 404 Não Encontrado.

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  Sua API pode produzir um conjunto padrão de códigos de resposta; nesse caso, você pode usar o atributo a seguir para especificar 200, 400 e 404 em vez de especificar cada um individualmente. Saiba mais sobre como usar as convenções da API Web.

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• Gere um operationId para aprimorar significativamente a experiência de consumo de API, incluindo documentação, geração de código e integração com outros serviços. Você pode gerar automaticamente o operationId incluindo a propriedade Name no filtro de verbo HTTP.

  [HttpGet("{Height}/{Width}", Name="GetPrice")]
  

Continuar