Documentação Viva com Swagger e .NET Core
C#
Olá pessoa!
Hoje vamos tocar em um assunto que muita gente não gosta, mas é MUITO importante: documentação!
Em um mundo integrado onde os sistemas se comunicam com muita frequência é difícil não precisarmos de uma documentação, eu sei, talvez você, como dev, não goste de ler isso. Mas é a verdade, além disso, a outra opção é você ter que conversar por telefone, e-mail ou sinal de fumaça com cada terceiro que fará a integração.
Se você não gostou da segunda opção, é porque ela é bem ruim mesmo! Além de ser chato conversar sobre endpoints e esclarecer essas coisas por telefone, também não é um modelo exatamente escalável.
O ideal é que sua aplicação tenha uma documentação própria e que todos os envolvidos em uma integração pudessem obter todas as informações necessárias através dela.
Certo, vamos escrever um doc? -Não, por favor não.
Não que escrever docs seja a pior coisa do mundo, spoiler: não são. Mas uma documentação deste tipo tende a ficar desatualizada com o tempo e uma documentação desatualizada serve para vários nadas. A documentação precisa ser viva, ou seja, software atualizou? Documentação precisa atualizar também!
Existem diversas maneiras diferentes para criarmos uma documentação viva, uma delas é o Swagger.
Swagger
O Swagger é um framework open-source para documentação de APIs, ele descreve os recursos disponíveis separando por controllers e actions, mostrando: parâmetros de entrada, retornos, códigos HTTP, autenticação e praticamente todas as informações de sua API.
Existem várias ferramentas para auxiliar nesse processo de criar a documentação utilizando Swagger, você pode encontrá-las pela internet aos montes, o que vamos fazer aqui é um pouco diferente, vamos configurar nossa aplicação para que ela mesma gere a documentação com nossos endpoints!
Vamos começar criando nossa aplicação .NET Core através do Visual Studio, na prática, se você criar a aplicação por linha de comando não verá nenhuma diferença, então sinta-se à vontade!
Com isso sua aplicação base é criada, contendo apenas o ValueController. Agora vamos preparar a aplicação para integração com o Swagger!
O primeiro passo é instalarmos o pacote SwashBuckle
em nossa aplicação:
PM> Install-Package Swashbuckle.AspNetCore
Com os pacotes instalados já é possível configurar a documentação. Para isso, vamos para a classe Startup
, responsável pela configuração dos serviços da aplicação. Faremos a alteração no método ConfigureServices
, por padrão este método contará apenas com uma instrução de: services.AddMvc();
. Nossa modificação acontecerá após essa instrução, conforme código:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(options =>
options.SwaggerDoc("beta",
new Info
{
Title = "Exemplo de documentação",
Version = "beta",
Description = "Projeto ASP.Net Core",
Contact = new Contact
{
Name = "Gabriel Schade",
Url = "https://gabrielschade.github.io"
}
})
);
}
Note que várias dessas informações você deverá preencher conforme o projeto, inclusive a versão (que informei como beta). Após isso, incluíremos algumas instruções no método Configure
, essas configurações criam o endpoint para visualizarmos a documentação.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(setup =>
{
setup.RoutePrefix = "swagger";
setup.SwaggerEndpoint("/swagger/beta/swagger.json", "Exemplo de documentação");
});
}
Só com estas alterações já conseguimos visualizar a página de documentação online! Para isso precisamos acessar a página "/swagger"
, conforme configurado anteriormente:
A página gerada é totalmente interativa, podendo inclusive realizar chamadas à sua API, o que pode ser bastante útil para os consumidores das APIs.
No entanto, ainda não configuramos um detalhe bastante importante, veja só como o endpoint Values/{id}
está sendo visualizado na documentação:
Apesar da action
estar listada, não conseguimos ver uma descrição humana da action
ou de seus parâmetros. Felizmente podemos fazer isso através dos comentários do próprio código!
/// <summary>
/// Método para obter todos os valores disponíveis
/// </summary>
/// <returns>
/// Retorna todos os valores
/// </returns>
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
/// <summary>
/// Método para obter um valor específico
/// </summary>
/// <param name="id">Id do valor que será obtido</param>
/// <returns>
/// Retorna o valor de acordo com o Id informado
/// </returns>
[HttpGet("{id}")]
public string Get(int id)
{
return "value";
}
/// <summary>
/// Método para publicar um valor de acordo com o parâmetro
/// </summary>
/// <param name="value">
/// Valor que deve ser publicado
/// </param>
[HttpPost]
public void Post([FromBody]string value)
{}
Note que inclui descrições relativamente genéricas, claro que isso porque esta API é apenas um exemplo. Em aplicações reais é importante descrever todas as características principais para comunicação com sua API, sem exceção.
Agora que já criamos os comentários precisamos informar para o Swagger a forma de carregâ-los. A primeira coisa a fazer é indicar em seu projeto, que você está gerando o arquivo XML com os comentários. Para fazer isso, acesse as propriedades de seu projeto e marque a opção: "XML Documentation file"
, conforme imagem:
Por fim, vamos voltar ao método ConfigureServices
e incluir as instruções na chamada ao método AddSwaggerGen
, conforme código:
services.AddSwaggerGen(options =>
{
string caminhoAplicacao = PlatformServices.Default.Application.ApplicationBasePath;
string nomeAplicacao = PlatformServices.Default.Application.ApplicationName;
string caminhoDocumentacao = Path.Combine(caminhoAplicacao, $"{ nomeAplicacao}.xml");
options.IncludeXmlComments(caminhoDocumentacao);
options.SwaggerDoc("beta",
new Info
{
Title = "Exemplo de documentação",
Version = "beta",
Description = "Projeto ASP.Net Core",
Contact = new Contact
{
Name = "Gabriel Schade",
Url = "https://gabrielschade.github.io"
}
});
});
Note que estou utilizando o caminho padrão para a documentação XML, caso você tenha escolhido outro caminho, é necessário incluí-lo aqui também.
Agora sim, ao acessar a página de documentação você verá suas actions e parâmetros comentados!
O mais legal é que o conceito de documentação viva realmente acontece aqui, vamos fazer o teste criando um novo Controller
. Este controlador será responsável pelo recurso de clientes e teremos apenas um método: ObterId
, este método receberá o CPF do cliente e retornará um identificador fictício, veja:
[Route("api/Cliente")]
public class ClienteController : Controller
{
/// <summary>
/// Método para obter o Id do cliente por CPF
/// </summary>
/// <returns>
/// Retorna o Id do cliente
/// </returns>
[HttpGet]
public Guid ObterId(string CPF)
=> Guid.NewGuid();
}
Só criamos um controller normalmente, certo? -Certo! E mesmo assim, ele já estará disponível na documentação, conforme imagem:
Você já pode inclusive testar seu método! Legal né?
Você pode encontrar a aplicação de exemplo com o Swagger configurado no meu Github. O que você achou deste post?
Me conte nos comentários!
E Até mais!
Sempre vale lembrar que as informações e textos aqui no blog representam minha opinião pessoal, o que pode não ser igual à sua ou de qualquer outra pessoa, incluindo a empresa para qual eu trabalho. Portanto as publicações inseridas aqui estão relacionadas somente a mim.