DOCUMENTANDO SUAS API´S COM SWAGGER

Atualmente é bem comum que empresas utilizem APIs REST para a integração de aplicações, seja para consumir serviços de terceiros ou prover novos serviços.
Ao consumir uma API existente, precisamos conhecer as funcionalidades disponíveis e detalhes de como invocá-las: recursos, URIs, métodos, Content-Types e outras informações.
As vezes passamos por dificuldades na hora de consumir uma API sem documentação, seja para saber quais os parâmetros devemos passar ou quais os métodos que estão disponíveis para serem usados, enfim, uma série de coisas que dificultam a vida do programador, o Swagger auxilia na hora de documentar nossas APIs, facilitando para o desenvolvedor que irá utilizar a sua API.

O que é exatamente o Swagger?

O Swagger é um projeto composto por algumas ferramentas que auxiliam o desenvolvedor de APIs REST em algumas tarefas como:
* Modelagem da API
* Geração de documentação (legível) da API
* Geração de códigos do Cliente e do Servidor, com suporte a várias linguagens de programação
O Swagger é uma representação simples da sua API RESTful, com uma documentação interativa, é o que eu irei mostrar daqui pra frente.

Na imagem abaixo temos o modelo de documentação com Swagger.

Adicionando o Swagger no seu projeto Web API

Adicionando as dependências:

PM> Install-Package Microsoft.AspNet.WebApi.Owin –version 5.2.0

PM> Install-Package Microsoft.Owin –version 3.0.0

PM> Install-Package Owin –version 1.0.0  

Adcionando o Swagger

PM> Install-Package Swashbuckle  

Após a instalação dos pacotes vamos iniciar a configuração do Swagger.
Crie uma nova classe com o nome “Startup” e adicione o código abaixo.

[assembly: OwinStartup(typeof(Swagger.Startup))]
namespace Swagger  
{
    public class Startup
    {
        public void Configuration(IAppBuilder app)
        {

            HttpConfiguration config = new HttpConfiguration();

            WebApiConfig.Register(config);

            Swashbuckle.Bootstrapper.Init(config);

            app.UseWebApi(config);

        }
    }
}

Na pasta App_Start do seu projeto, foi adicionada a classe “SwaggerConfig” . Nessa classe é onde será realizada toda configuração do Swagger. Para o swagger exibir os comentários é necessário habilitar o “XML documentation file”.
Clique com o botão direito do mouse sobre o projeto, vá em Build na sessão OutPut path selecione o XML documentation file.

Volte para a classe “SwaggerConfig” e adicione o código abaixo.

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]
namespace Swagger  
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);

            SwaggerSpecConfig.Customize(c =>
            {
                c.IncludeXmlComments(GetXmlCommentsPath());
            });
        }

        protected static string GetXmlCommentsPath()
        {
            return string.Format(@"{0}\bin\Swagger.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }
    }
}

Para finalizar adicione a rota para sua controller e as de seus serviços.

[RoutePrefix("api/Produtos")]
public class ProdutosController : ApiController  

Métodos de sua controller:

/// <summary>
/// Retorna todos os produtos
/// </summary>
/// <remarks>Retorna um array com todos os Produtos</remarks>
/// <response code="500">Internal Server Error</response>
[Route("")]
[ResponseType(typeof(List<Produto>))]
public IHttpActionResult Get()  
{
    return Ok(ProdutosList);
}

/// <summary>
/// Get Produto
/// </summary>
/// <param name="Nome">Nome</param>
/// <remarks>Retorna o Produto pelo o nome informado</remarks>
/// <response code="404">Not found</response>
/// <response code="500">Internal Server Error</response>
[Route("{Nome:alpha}", Name = "RetornaProdutoPeloNome")]
[ResponseType(typeof(Produto))]
public IHttpActionResult Get(string Nome)  
{

    var Produto = ProdutosList.Where(s => s.Nome == Nome).FirstOrDefault();

    if (Produto == null)
    {
        return NotFound();
    }

    return Ok(Produto);
}

Espero que tenham gostado, qualquer dúvida, crítica ou sugestão só deixar um comentário.
David Barbosa