Há algum tempo eu comentei aqui sobre REST e WSDL, onde a ideia era apontar a maneira de se trabalhar com serviços sem a necessidade de ter um schema que define o que serviço disponibiliza e, principalmente, toda a estrutura das mensagens (SOAP) que são trocadas entre as partes.
Mas é importante dizer que mesmo serviços baseados em REST, também precisam, de alguma forma, expor alguma espécie de documentação, para descrever as ações que as APIs estão disponibilizando aos consumidores, apontando o caminho (URI) até aquele ponto, método/verbo (HTTP), informações que precisam ser passadas, formatos suportados, etc.
A ideia é apenas ser informativo, ou seja, isso não será utilizado pelo cliente para a criação automática de uma proxy. Pensando nisso, a Microsoft incluiu no ASP.NET Web API a opção para gerar e customizar as documentações de uma API.
Mas a documentação é sempre exibida, na maioria das vezes, de forma amigável ao consumidor, para que ele possa entender cada uma das ações, suas exigências, para que ele possa construir as requisições da forma correta. Sendo assim, podemos na própria aplicação onde nós temos as APIs, criar um controller que retorna uma view (HTML), contendo a descrição das APIs que estão sendo hospedadas naquela mesma aplicação.
public class DeveloperController : Controller
{
public ActionResult Apis()
{
var explorer = GlobalConfiguration.Configuration.Services.GetApiExplorer();
return View(explorer.ApiDescriptions);
}
}
Note que estamos recorrendo ao – novo – método GetApiExplorer, disponibilizado através da configuração global das APIs. Este método retorna um objeto que implementa a interface IApiExplorer, que como o próprio nome sugere, define a estrutura que permite obter a descrição das APIs. Nativamente já temos uma implementação chamada ApiExplorer, que materializa todoas as APIs em instâncias da classe ApiDescription, e uma coleção deste objeto é retornada através da propriedade ApiDescriptions, e que repassamos para que a view possa renderizar isso.
Na view, tudo o que precisamos fazer é iterar pelo modelo, e cada elemento dentro deste laço representa uma ação específica que está dentro da API. A classe que representa a ação, possui várias propriedades, fornecendo tudo o que é necessário para que os clientes possam consumir qualquer ums destas ações. Abaixo temos o código que percorre e exibe cada uma delas:
@model IEnumerable<System.Web.Http.Description.ApiDescription>
<body>
@foreach (var descriptor in this.Model)
{
<ul>
<li><b>@descriptor.HttpMethod – @descriptor.RelativePath</b></li>
<li>Documentation: @descriptor.Documentation</li>
@if (descriptor.SupportedResponseFormatters.Count > 0)
{
<li>Media Types
<ul>
@foreach (var mediaType in descriptor.SupportedResponseFormatters.Select(
mt => mt.SupportedMediaTypes.First().MediaType))
{
<li>@mediaType</li>
}
</ul>
</li>
}
@if (descriptor.ParameterDescriptions.Count > 0)
{
<li>Parameters
<ul>
@foreach (var parameter in descriptor.ParameterDescriptions)
{
<li>Name: @parameter.Name</li>
<li>Type: @parameter.ParameterDescriptor.ParameterType</li>
<li>Source: @parameter.Source</li>
}
</ul>
</li>
}
</ul>
}
</body>
Ao acessar essa view no navegador, temos a relação de todas as ações que estão expostas pelas APIs. A visibilidade das ações é controlada a partir do atributo ApiExplorerSettingsAttribute, que possui uma propriedade boleana chamada IgnoreApi, que quando definida como True, omite a extração e, consequentemente, a sua visualização.
É importante notar que na imagem acima, estamos apresentando a propriedade Documentation. A mensagem que aparece ali é uma customização que podemos fazer para prover essa informação, extraindo-a de algum lugar. Para definir a descrição da ação, vamos criar um atributo customizado para que quando decorado no método, ele será extraído por parte da infraestrutura do ASP.NET, alimentando a propriedade Documentation. O primeiro passo, consiste na criação de um atributo para definir a mensagem:
[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
public class ApiDocumentationAttribute : Attribute
{
public ApiDocumentationAttribute(string message)
{
this.Message = message;
}
public string Message { get; private set; }
}
O próximo passo é decorá-lo em cada uma das ações que quisermos apresentar uma informação/descrição. A classe abaixo representa a nossa API, e o atributo recentemente criado foi decorado em todas as ações, descrevendo suas respectivas funcionalidades:
public class ClientesController : ApiController
{
[ApiDocumentation(“Retorna todos os clientes.”)]
public IEnumerable<Cliente> Get()
{
//…
}
[ApiDocumentation(“Retorna um cliente pelo seu Id.”)]
public Cliente Get(int id)
{
//…
}
[ApiDocumentation(“Inclui um novo cliente.”)]
public void Post(Cliente cliente)
{
//…
}
[ApiDocumentation(“Exclui um cliente existente.”)]
public void Delete(int id)
{
//…
}
}
Só que o atributo por si só não funciona. Precisamos de algum elemento para extrair essa customização que fizemos, e para isso, a temos uma segunda interface, chamada IDocumentationProvider, que fornece dois métodos com o mesmo nome: GetDocumentation. A diferença entre eles é o parâmetro que cada um deles recebe. O primeiro recebe um parâmetro do tipo HttpParameterDescriptor, o que permitirá descrever, também, cada um dos parâmetros de uma determinada ação. Já o segundo método, recebe um parâmetro do tipo HttpActionDescriptor, qual utilizaremos para extrair as informações pertinentes à uma ação específica.
public class ApiDocumentationAttributeProvider : IDocumentationProvider
{
public string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
{
return null;
}
public string GetDocumentation(HttpActionDescriptor actionDescriptor)
{
var attributes =
actionDescriptor.GetCustomAttributes<ApiDocumentationAttribute>();
if (attributes.Count > 0)
return attributes.First().Message;
return null;
}
}
Aqui extraímos o atributo que criamos, e se ele for encontrado, retornamos o valor definido na propriedade Message. A ausência deste atributo, faz com que um valor nulo seja retornado, fazendo com que nenhuma informação extra seja incluída para a ação.
E, finalmente, para incluir o provedor de documentação ao runtime do ASP.NET, recorremos à configuração das APIs, substituindo qualquer implementação existente para este serviço, para o nosso provedor que extraí a documentação do atributo customizado.
GlobalConfiguration.Configuration.Services.Replace(
typeof(IDocumentationProvider),
new ApiDocumentationAttributeProvider());
Israel Aece 