Want create site? Find Free WordPress Themes and plugins.

Fala Galera,

Hoje meu post irá falar sobre como podemos documentar nossas API REST. Documentar nunca foi e nunca será uma tarefa das mais legais geralmente é monótono, cansativo e trabalhoso. Documentação tende-se a se perder a longo do tempo e facilmente ficar desatualizado.

E ai que surgiu o Swagger, ele é um framework que automatiza a documentação, com ele você pode descrever, consumir e visualizar sua API REST. O interessante do Swagger é que ele mantém sua documentação sempre sincronizada tanto no lado cliente quanto no lado servidor já que ele está integrado diretamente ao código.

Swagger é um Framework multi linguagem e existem diversas implementações nas mais diversas tecnologias e a sua implementação para o ASP.NET Web API se chama “Swashbuckle”. Essa implementação facilita nossa vida já que basta adicionar o Swagger em qualquer projeto ASP.NET Web API e que como um passe de mágica sua API terá uma documentação maravilhosa. Outra coisa bem legal do Swagger é que ele não necessita de nenhuma dependência então basta adicionar o pacote via NuGet para habilitar a documentação de sua API.

Ao instalar o pacote Swagger com ele vem incorporado o Swagger-UI que basicamente é uma interface que gera dinamicamente as documentação da sua API e um Sandbox no qual podemos fazer os testes e a chamadas na nossa API e tudo isso de forma automática.

A figura abaixo mostra o Swagger e sua interface gráfica

swagger

A figura abaixo mostra o Sandbox do Swagger aonde podemos realizar os testes

swagger2

Utilizando o Swagger no ASP.NET Web Api

Para utilizar o Swagger, devemos adicionar o Swagger como dependência do nosso projeto, o Swagger está disponível via NuGet. Execute o comando abaixo no Package Manager Console

Install-Package Swashbuckle

Com o pacote do Swagger instalado, ele irá criar uma arquivo de inicialização (bootstrap) que está localizado em App_Start/SwaggerConfig.cs.

Agora com precisamos chamar o Swagger no processo de start up da nossa aplicação então vamos abrir a WebApiConfig.cs e adicionar o código abaixo

namespace Swagger
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {

            // Web API routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

            SwaggerConfig.Register();
        }
    }
}

Vamos agora habilitar o Swagger para que use a documentação gerada pelo XML Comments. Para isso devemos primeiro habilitar a geração dos xml de documentação.

Vamos abrir a propriedades do projeto e marcar a opção XML documentation file na aba build, conforme figura abaixo

swagger3

Com a geração de XML Comments habilitada, vamos colocar o Swagger para ler essa documentação. Vamos abrir o SwaggerConfig.cs e adicionar o código abaixo:

namespace Swagger
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration 
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "Swagger Sample");
                        c.IncludeXmlComments(GetXmlCommentsPath());
                    })
                .EnableSwaggerUi(c =>
                    {

                    });
        }

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

Para o exemplo de nossa documentação criei um simples Controller chamado Account e uma única rota chamada Register

namespace Swagger.Controllers
{
    [RoutePrefix("api/Account")]
    public class AccountController : ApiController
    {

        /// <summary>
        /// Register a new user on application
        /// </summary>
        /// <param name="user">New user to register</param>
        /// <remarks>Adds new user to application and grant access</remarks>
        /// <response code="400">Bad Request</response>
        /// <response code="500">Internal Server Error</response>
        [AllowAnonymous]
        [Route("Register")]
        [ResponseType(typeof(RegisterBindingModel))]
        [HttpPost]
        public async Task<IHttpActionResult> Register(RegisterBindingModel user)
        {
            //IMPLEMENTATION OF CODE GOES HERE!!
            throw new NotImplementedException();
        }
    }
}

Veja agora o resultado quando executamos nossa aplicação

swagger4

Como podemos ver, o Swagger detalhou todo o nossa rota e colocou em sua interface gráfica assim podemos saber para que serve, como fazer a requisição e quais parâmetros devemos passar.

Com o Swagger podemos não somente detalhar melhor nossas API como também podemos customizar toda a interface, alterando cores, fontes, css e etc.

Quer saber mais sobre o Swagger, clique aqui.

O código deste exemplo se encontra no meu GitHub através deste link

Abs e até a próxima

Rafael Cruz

É desenvolvedor .NET há mais de 12 anos, certificado Microsoft desde de 2006, instrutor oficial Microsoft há 5 anos, Pós Graduado em Engenharia de Software pela UFRJ, suas certificações são Microsoft Certified Trainer, Microsoft Certified Solution Developer (Web, Application Lifecycle Management), Microsoft Certified Professional Developer, Microsoft Certified Tecnology Specialist.
Atualmente trabalha como arquiteto de sistema, escreve artigos no .NET Coders e no seu blog rafaelcruz.azurewebsites.net para compartilhar experiências na área de desenvolvimento Web, Aplicativos Móveis e Cloud Solutions.

Twitter LinkedIn 

Did you find apk for android? You can find new Free Android Games and apps.

Comentários

comentarios