Com cada vez mais aplicações multiplataformas, é comum definir uma API REST que será consumida pelas várias versões da aplicação. Mas com vários times tendo acesso a API, não basta mais apenas desenvolvê-la e esperar que todos consigam utilizá-la institivamente.
Na época do web service, existia o WSDL que funcionava como uma documentação, já que facilitava a criação dos clientes que iria consumí-lo. Com as APIs REST não temos esta facilidade, assim, torna-se imprescindível que ela seja bem documentada.
Mas como realizar esta documentação? Existem algumas ferramentas que podem nos auxiliar neste processo, como: API Blueprint, RAML, Swagger, entre outras.
Como o nome deste artigo sugere, aqui abordaremos o Swagger.
Curso C# (C Sharp) - APIs REST com ASP.NET Web API
Conhecer o cursoSwagger
O Swagger é uma aplicação open source que auxilia os desenvolvedores a definir, criar, documentar e consumir APIs REST. Sendo uma das ferramentas mais utilizadas para esta função, a empresa por trás dela (a SmartBear Software), decidiu criar o Open API Iniciative e renomearam as especificações do Swagger para OpenAPI Specification.
Ela visa padronizar as APIs REST, desta forma descreve os recursos que uma API deve possuir, como endpoints, dados recebidos, dados retornados, códigos HTTP, métodos de autenticação, entre outros.
Para facilitar o processo de especificação/documentação de uma API, o Swagger fornece algumas ferramentas, como:
- Swagger Editor: Editor que permite especificar uma API. Há uma versão online grátis e aplicativos para desktop;
- Swagger UI: Interface interativa para a documentação da API;
- Swagger Codegen: Gera templates de código (mais de 20 linguagens estão disponíveis) de acordo com uma especificação de API.
Neste artigo vamos focar na documentação de uma API existente, criada em ASP.NET Core Web API.
Especificação do Swagger
O ponto mais importante do Swagger é a sua especificação, que era chamada de Swagger specification e agora é OpenAPI Specification. Esta especificação trata-se de um documento, JSON ou YAML, que define a estrutura da API. Indicando os endpoints, formatos de entrada, de saída, exemplos de requisições, forma de autenticação, etc.
Abaixo você pode ver um exemplo desta especificação definida em JSON:
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "API V1"
},
"basePath": "/",
"paths": {
"/api/Example": {
"get": {
"tags": [
"Example"
],
"operationId": "ApiExampleGet",
"consumes": [],
"produces": [
"text/plain",
"application/json",
"text/json"
],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Item"
}
}
}
}
},
"post": {
...
}
},
"/api/Example/{id}": {
"get": {
...
},
"put": {
...
},
"delete": {
...
},
"definitions": {
"Item": {
"type": "object",
"properties": {
"id": {
"format": "int64",
"type": "integer"
},
"name": {
"type": "string"
},
"isValid": {
"default": false,
"type": "boolean"
}
}
}
},
"securityDefinitions": {}
}
É possível definir esta especificação na mão, olhando as opções na documentação, através do Swagger Editor ou utilizando outra ferramenta para gerá-la.
No ASP.NET Core podemos utilizar duas bibliotecas para gerar este documento:
Por ser mais completa, faremos uso da Swashbuckle.
Adicionando o Swashbuckle na aplicação
Para este exemplo, estou utilizando uma aplicação ASP.NET Core Web API, baseada no exemplo fornecido pela documentação da Microsoft, que pode ser vista aqui. Você pode ver a aplicação que criei no meu Github.
Com a aplicação Web API criada, inicialmente é necessário adicionar o pacote do Swashbuckle na aplicação. Ele possui três componentes:
- Swashbuckle.AspNetCore.Swagger;
- Swashbuckle.AspNetCore.SwaggerGen;
- Swashbuckle.AspNetCore.SwaggerUI;
Mas é necessário instalar apenas o pacote Swashbuckle.AspNetCore. Por se tratar de uma aplicação .NET Core, este pacote pode ser adicionado com o comando abaixo:
dotnet add package Swashbuckle.AspNetCore
Após isso, para que o arquivo de especificação da API do Swagger seja criado, é necessário adicionar o gerador dele nos serviços da aplicação, no método ConfigureServices da classe Startup:
public void ConfigureServices(IServiceCollection services)
{
//... código omitido
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "TodoAPI", Version = "v1" });
});
}
Para a classe Info, defina o using do namespace abaixo:
using Swashbuckle.AspNetCore.Swagger;
Agora, no método Configure é necessário ativar o Swagger e indicar o local onde o seu arquivo de especificação será criado:
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
//Ativa o Swagger
app.UseSwagger();
// Ativa o Swagger UI
app.UseSwaggerUI(opt =>
{
opt.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoAPI V1");
});
//... código omitido
}
Com isso, através de reflection a biblioteca consegue especificar os endpoints da aplicação.
Caso seja executada, podemos acessar o Swagger UI da aplicação no caminho /swagger:
Caso queira que o Swagger UI seja acessado a partir da raiz da aplicação, na ativação dela, no método Configure, atribua vazio para a propriedade RoutePrefix:
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoAPI V1");
c.RoutePrefix = string.Empty;
});
Customizando o Swagger
Como o Swashbuckle trabalha com reflection, podemos fazê-lo gerar mais informações das nossas APIs com base em configurações definidas nela.
Comentários de documentação
Sabemos que no C# podemos adicionar comentários de documentação nos nossos códigos, como:
/// <summary>
/// Lista os itens da To-do list.
/// </summary>
/// <returns>Os itens da To-do list</returns>
/// <response code="200">Returna os itens da To-do list cadastrados</response>
[HttpGet]
public ActionResult<List<Item>> Get()
{
return _repository.GetAll();
}
É possível fazer o Swashbuckle ler esses comentários e assim tornar a especificação da API mais detalhada.
Para isso, na definição de geração do arquivo de especificação, no método ConfigureServices deve ser adicionado a informação abaixo:
services.AddSwaggerGen(opt =>
{
opt.SwaggerDoc("v1", new Info { Title = "TodoAPI", Version = "v1" });
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
opt.IncludeXmlComments(xmlPath);
});
Note que estamos indicando que ele deve ler os comentários do código a partir de um arquivo XML. Para que eles sejam gerados neste arquivo indicado, no arquivo de configuração do projeto (o .csproj), adicione o trecho abaixo:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
O <NoWarn> é definido para que a IDE não exiba um alerta sobre os códigos que não possuírem comentários de documentação.
Agora ao acessar o Swagger API, o que foi definido em <summary> será mostrado:
Também podemos o <remarks> para indicar um exemplo de requisição:
// POST api/todo
/// <summary>
/// Cria um item na To-do list.
/// </summary>
/// <remarks>
/// Exemplo:
///
/// POST /Todo
/// {
/// "id": 1,
/// "name": "Item1",
/// "iscomplete": true
/// }
///
/// </remarks>
/// <param name="value"></param>
/// <returns>Um novo item criado</returns>
/// <response code="201">Retorna o novo item criado</response>
/// <response code="400">Se o item não for criado</response>
[HttpPost]
public ActionResult<Item> Post([FromBody] Item value)
{
Console.WriteLine(value?.Name);
var item = _repository.Save(value);
if(item != null)
return item;
return BadRequest();
}
O resultado será:
Com as anotações ProducesResponseType e Produces podemos indicar os códigos HTTP e o tipo de dado que os endpoints irão retornar:
[Authorize]
[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
//..código omitido
// GET api/todo
/// <summary>
/// Lista os itens da To-do list.
/// </summary>
/// <returns>Os itens da To-do list</returns>
/// <response code="200">Returna os itens da To-do list cadastrados</response>
[HttpGet]
[ProducesResponseType(200)]
public ActionResult<List<Item>> Get()
{
return _repository.GetAll();
}
//... código omitido
}
Especificando a autenticação
Uma das principais vantagens de adicionar o Swagger na aplicação, é poder testar os endpoints pela Swagger UI. Quando a aplicação define autenticação, é necessário indicar isso para o Swashbuckle, para que ele também gere uma especificação desde detalhe.
Com isso, será possível testar os endpoints pela Swagger UI utilizando a autenticação definida.
Para fazer isso, devemos adicionar a informação abaixo, na definição de geração do arquivo de especificação, no método ConfigureServices:
services.AddSwaggerGen(opt =>
{
opt.SwaggerDoc("v1", new Info { Title = "TodoAPI", Version = "v1" });
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
opt.IncludeXmlComments(xmlPath);
var security = new Dictionary<string, IEnumerable<string>>
{
{"Bearer", new string[] { }},
};
opt.AddSecurityDefinition(
"Bearer",
new ApiKeyScheme
{
In = "header",
Description = "Copie 'Bearer ' + token'",
Name = "Authorization",
Type = "apiKey"
});
opt.AddSecurityRequirement(security);
});
Acima estamos definindo que a aplicação faz uso de autenticação do tipo JWT Token (“Bearer Token”). Na documentação do Swagger, você pode ver os outros tipos de autenticação suportados.
Ao acessar o Swagger UI, ele irá mostrar o botão “Autorize”:
Ao clicar nele, é possível informar o tipo de autenticação especificado:
Com isso, mesmo que necessite de autenticação, será possível realizar as requisições dos endpoints da aplicação pelo Swagger UI.
Descrição
Por fim, é possível descrever um pouco da aplicação através das propriedades da classe Info da especificação do Swagger:
services.AddSwaggerGen(opt =>
{
opt.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "Todo API",
Description = "Um exemplo de aplicação ASP.NET Core Web API",
TermsOfService = "Não aplicável",
Contact = new Contact
{
Name = "Wladimilson",
Email = "contato@treinaweb.com.br",
Url = "https://treinaweb.com.br"
},
License = new License
{
Name = "CC BY",
Url = "https://creativecommons.org/licenses/by/4.0"
}
});
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
opt.IncludeXmlComments(xmlPath);
var security = new Dictionary<string, IEnumerable<string>>
{
{"Bearer", new string[] { }},
};
opt.AddSecurityDefinition(
"Bearer",
new ApiKeyScheme
{
In = "header",
Description = "Copie 'Bearer ' + token'",
Name = "Authorization",
Type = "apiKey"
});
opt.AddSecurityRequirement(security);
});
O resultado será:
Conclusão
O Swagger é uma ótima forma de documentar APIs REST e com a biblioteca Swashbuckle, podemos gerar o arquivo de especificação do Swagger com facilidade. Assim, não há mais desculpa para se definir documentações interativas e detalhadas para as suas APIs REST.
