DEV Community

loading...

Swagger — Turbinando sua documentação (Parte I)

Nelson Souza
・5 min read

Olá tudo bem? Escrevi no ano passado um post explicando como customizar a cara do Swagger. Pode ver o post aqui: Swagger — Customizando Swagger UI.

Continuando com mais dicas, vamos acrescentar mais algumas coisas interessantes. Separei algumas configurações específicas (diria até que são boas práticas da própria ferramenta), quais uso nos projetos.

Será um pouco longo, então irei dividir em mais partes, mas vou colocar tudo que eu consegui me lembrar. Então vamos lá!

Iniciando as configurações

Como as para começar totalmente do zero, vamos criar um projeto simples de Web API, em branco. Chamei de DemoSwagger.

Vamos adicionar a biblioteca do Swagger no projeto o Package Manager Console:

install-Package Swashbuckle.AspNetCore

E nosso arquivo Startup.cs ficará assim com as configurações básicas:

Criei uma classe Products que irá retornar uma coleção de dados. Super simples:

Vou também acrescentar uma controller simples chamada ProductsController com os 4 métodos básicos: GET/POST/PUT/DELETE:

Vamos acessar a url do Swagger diretamente:

app.UseSwaggerUI(options =>  
{  
   options.RoutePrefix = string.Empty;  
}
Enter fullscreen mode Exit fullscreen mode

Desta forma, aquela opção de colocar swagger pode ser removida. Esta opção nos permite informar como será a rota principal do Swagger. Pode experimentar por exemplo: docs/swagger.

Neste caso para sempre carregar nesta última rota que exemplifiquei, teremos que colocar esse caminho:

app.UseSwaggerUI(options =>  
{  
   options.RoutePrefix = "docs/swagger";  
}
Enter fullscreen mode Exit fullscreen mode

É muito comum ser usado o string.Empty sem esta opção nas propriedades do projeto.

Mas, fica a seu critério.

Se tudo deu certo e nada deu errado, ao executar o programa irá aparecer essa página:

Dito tudo isso e configurado certinho, vamos às brincadeiras!

Usando API Conventions

Esse cara tem a função de expor de forma simples códigos de resposta padrão aos seus métodos de controlador. Pode ser utilizado diretamente no método ou direto na controller. Vamos às duas formas.

Antes:

Vamos adicionar a convenção diretamente em nosso método:

[HttpGet]  
[ApiConventionMethod(typeof(DefaultApiConventions), nameof(DefaultApiConventions.Get))]
public IActionResult Get()  
{  
   var items = Product.GetProducts();  
   return Ok(items);  
}
Enter fullscreen mode Exit fullscreen mode

Ou diretamente na Controller:

[Route("api/[controller]")]  
[ApiController]  
[ApiConventionType(typeof(DefaultApiConventions))]
public class ProductsController : ControllerBase
Enter fullscreen mode Exit fullscreen mode

Resultado agora com status 200, 400 e default:

Método GET

Método POST

Por que isso ocorre? Basta entrar na classe DefaultApiConventions e ver o conteúdo dela. Veja que temos os ProducesResponseType já simplesmente implementados, de acordo os 4 verbos básicos: GET/POST/PUT/DELETE:

Extra: podemos implementar diretamente na classe Startup:

Customizando Conventions

Como o nome já diz, vamos customizar uma convenção. Para isso vamos criar uma classe simples chamada CustomConventions. Ela deve ser estática, assim como seus métodos. Nada mais será do que uma cópia de nossa amiga classe DefaultApiConventions:

public static class CustomConventions  
{  
   [ProducesDefaultResponseType]  
   [ProducesResponseType(StatusCodes.Status200OK)]  
   [ProducesResponseType(StatusCodes.Status400BadRequest)]  
   [ProducesResponseType(StatusCodes.Status404NotFound)]  
   [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]  
   public static void Get()  
   { 
   }  
}
Enter fullscreen mode Exit fullscreen mode

Observe que criei o nome do mesmo nome de método que está na controller e implementei suas convenções customizadas adicionando o BadRequest que não tinha na classe DefaultApiConventions. Podem ser todos os verbos que você achar que devem ser implementados. Fica por sua conta e risco. 😃

Agora podemos usar da mesma forma que usamos as convenções padrão:

[HttpGet]  
[ApiConventionMethod(typeof(CustomConventions), nameof(CustomConventions.Get))]
public IActionResult Get()  
{  
    var items = Product.GetProducts();  
    return Ok(items);  
}
Enter fullscreen mode Exit fullscreen mode

Ou diretamente na controller:

[Route("api/[controller]")]  
[ApiController]  
[ApiConventionType(typeof(CustomConventions))]
public class ProductsController : ControllerBase
Enter fullscreen mode Exit fullscreen mode

Também pode na classes Startup:

[assembly: ApiConventionType(typeof(CustomConventions))]  
public class Startup  
{

}
Enter fullscreen mode Exit fullscreen mode

Resultado:

Gerando o XML dos comentários (Summary)

Primeiro precisamos configurar umas coisas no projeto. Abra as propriedades do mesmo e marque a opção de XML document file:

Em nossa classe Startup, agora teremos isso:

Colocamos um comentário simples no método de GET e executamos o projeto:

Ok até aqui. Editando o arquivo de projeto temos isso, um caminho medonho onde salva o XML:

Vamos melhorar com isso:

Agora vejamos como ficou o caminho nas propriedades do projeto:

Mas ainda não está bom. E a versão de Release? Bom… não será gerado. Então, para isso vamos mudar umas coisas:

Remova essa linha:

Agora o pulo do gato 😺 — Configure desta forma:

Essa configuração servirá para Debug e Release, assim sempre será gerado o arquivo de documentação.

Comentários sem uso de configuração XML

Sim, isso também é possível. Talvez seja um pouco mais trabalhoso, mas o efeito acaba sendo o mesmo. Mas, primeiro vamos a algumas configurações:

Instale o pacote Swashbuckle.AspNetCore.Annotations:

install-Package Swashbuckle.AspNetCore.Annotations
Enter fullscreen mode Exit fullscreen mode

Este pacote nos permitirá usar alguns atributos para documentação de nossos endpoints.

Agora iremos remover tudo relacionado ao XML anterior:

  • Edite o arquivo *.csproj e remova a tag:

GenerateDocumentationFile

Nas propriedades do projeto, remova a opção de XML document file:

E na classe Startup vamos incluir a extensão EnableAnnotations:

services.AddSwaggerGen(options =>  
{  
   options.EnableAnnotations();  
}
Enter fullscreen mode Exit fullscreen mode

Vamos usar um exemplo na controller de Products, usando o atributo SwaggerOperation:

Esse atributo possui outros parâmetros como: OperationId e Tags, mas não precisamos neste momento.

Referências

https://stackedit.io/
https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1

Discussion (0)

Forem Open with the Forem app