.NET

12 jun, 2018

Documentação de APIs com Swagger no ASP.Net Core

Publicidade

Não basta apenas desenvolver nossas aplicações e largar nas mãos dos times que farão uso delas. Uma boa documentação é um dos quesitos chave para o sucesso de todo sistema hoje em dia, ainda mais no mundo de APIs que vivemos hoje, onde existem cada vez mais integrações entre aplicações e serviços.

Imagine você ter que entrar em contato com o desenvolvedor de determinada API para saber quais endpoints você precisa usar, e quais são os parâmetros necessários para a correta integração com seu sistema. Tanto você, quanto ele ficarão loucos com as trocas de e-mails e telefonemas. Você também não precisa escrever um documento que detalhe o funcionamento de sua API no Word – esqueça isso!

Hoje vamos ver como criar uma documentação de API efetiva com o Swagger.

Não deixe de conferir um dos meus projetos de exemplo, onde eu faço uso do Swagger. Está disponível em meu Github.

O que é o Swagger?

O Swagger é um framework open source que ajuda os desenvolvedores no desenho, especificação e documentação de suas APIs. Ele segue a iniciativa Open API que busca a padronização de APIs REST. Essa especificação basicamente descreve os recursos de suas APIs, como endpoints, parâmetros de entrada, objetos de retorno, códigos HTTP, métodos de autenticação, entre outros.

O Swagger possui algumas ferramentas que nos auxiliam em todo o processo de desenvolvimento de nossas APIs, entre elas:

  • Swagger Editor: ditor online para criar especificações Open API
  • Swagger UI: renderiza especificações Open API em uma interface interativa
  • Swagger CodeGen: gera templates de código a partir de uma especificação Open API

Configurando o Swagger no ASP.Net Core

Não é necessário criar um arquivo de especificação do Swagger ao utilizar o ASP.Net; podemos gerar a especificação em tempo de execução de forma automática usando a biblioteca Swashbuckle, que conta com versões para ASP.Net (full framework) e ASP.Net Core.

Primeiramente você deve instalar o pacote nuget Swashbuckle.AspNetCore em seu projeto de API.

dotnet add package Swashbuckle.AspNetCore --version 2.5.0

Em seguida, no arquivo Startup.cs do seu projeto será necessário adicionar a configuração necessária para a geração da especificação do Swagger. Isso deve ser feito no método ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
	services.AddSwaggerGen(options =>
	{
		options.SwaggerDoc("v1",
			new Info
			{
				Title = "Demo Jwt",
				Version = "v1",
				Description = "Projeto de demonstração ASP.Net Core",
				Contact = new Contact
				{
					Name = "Wellington Nascimento",
					Url = "https://github.com/wellingtonjhn"
				}
			});
	});
}

public void Configure(IApplicationBuilder app)
{
	app.UseSwagger();
	app.UseSwaggerUI(c =>
	{
		c.RoutePrefix = "swagger";
		c.SwaggerEndpoint("/swagger/v1/swagger.json", "Demo JWT Api");
	});
	
	app.UseMvc();
}

Com isso, você já pode rodar sua API e acessar a documentação através do endpoint /swagger. Se você quiser modificar essa rota, basta alterar a propriedade RoutePrefix da configuração ao chamar o método UseSwaggerUI.

Perceba que você pode fazer as chamadas para os recursos de sua API diretamente pela interface do Swagger. Informe os parâmetros necessários e clique no botão “Try it out!“.

Caso sua API necessite de autenticação para ser acessada, você pode configurar o schema de autenticação usando o método AddSecurityDefinition. No meu caso, estou usando ApiKeyScheme, que representa autenticação baseada em token. Para conhecer outros schemas de autenticação do Swagger, recomendo a leitura da documentação.

public void ConfigureServices(IServiceCollection services)
{
	services.AddSwaggerGen(options =>
	{
		// ... código omitido
		
		options.AddSecurityDefinition(
			"bearer",
			new ApiKeyScheme
			{
				In = "header",
				Description = "Autenticação baseada em Json Web Token (JWT)",
				Name = "Authorization",
				Type = "apiKey"
			});
	});
}

Com isso, o botão “Authorize” será exibido no cabeçalho da interface do Swagger.

Ao clicar nele, será exibida uma janela onde você deve inserir seu token de acesso. No meu caso, estou utilizando schema de autenticação Bearer com JWT.

Você também pode usar os comentários de documentação XML (summary) do .Net e deixar sua documentação do Swagger mais rica. Para isso, use o método IncludeXmlComments informando o path onde está o arquivo gerado com os comentários.

public void ConfigureServices(IServiceCollection services)
{
	services.AddSwaggerGen(options =>
	{
		// ... código omitido
		
		var applicationBasePath = PlatformServices.Default.Application.ApplicationBasePath;
		var applicationName = PlatformServices.Default.Application.ApplicationName;
		var xmlDocumentPath = Path.Combine(applicationBasePath, quot;{applicationName}.xml");

		if (File.Exists(xmlDocumentPath))
		{
			options.IncludeXmlComments(xmlDocumentPath);
		}
	});
}

Para ativar a geração do arquivo de comentários XML, vá nas propriedades do seu projeto de API, clique na guia Build, e em seguida marque a opção “XML documentation file”, deixando o path padrão.

Durante o build de sua aplicação, o arquivo de documentação XML será gerado no local especificado, e com isso sua documentação do Swagger irá exibir essas mesmas informações.

Conclusão

Como vimos, com a simples adição do Swagger em nossa aplicação, qualquer consumidor conseguirá de forma efetiva usar nossa API.

Além dos recursos descritos nesse artigo, você também pode criar filtros de execução do Swagger, onde por exemplo, você pode omitir determinadas propriedades de modelos da documentação, exibir os endpoints em caixa baixa.

Caso você use versionamento em suas APIs, será necessário fazer a configuração no Swagger, mas deixarei para explicar isso em outro artigo.

Espero que tenham gostado!

Se ficou qualquer dúvida ou tenham críticas e sugestões, não deixem de entrar em contato.

Abraços!

Referências