O Swagger é uma ferramenta muito poderosa que pode nos auxiliar na documentação de nossas APIs. Ela é mantida pela SmartBear Software e é uma ferramenta open-source.

Quando criamos uma aplicação .Net, nem nos damos conta muitas das vezes que este recurso já está no template de projetos do .Net Core WebApi.

Mas acredito que seja interessante escrever sobre e demonstrar como habilitar, quando você não tem em seu projeto ou está migrando um projeto legado e deseja utiliza-lo.

Basicamente o Swagger vai nos permitir. como já mencionado, uma documentação interativa para nossas APIs.

Eu vou listar alguns itens que acho importante conhecemos sobre o Swagger antes de passar para um exemplo de implementação. Caso esteja buscando apenas como implementar, você pode pular lá para baixo do artigo.

Histórico sobre o Swagger

Tony Tam criou o projeto da API do Swagger quando desenvolvia ferramentas para o site de dicionário, o Wordnik. O framework foi desenvolvido para auxiliar na documentação e automatização das API.

Foi dai que o projeto se tornou open source e a partir dai, ganhou engajamento entre companias e desenvolvedores.

Em 2015, a empresa que mantinha o Swagger, a SmartBear Software que mencionei anteriormente, ajudou a fundar o projeto ou iniciativa OpenAPI, uma organização que é patrocinada e mantida pela Linux Foundation.

Um ano depois, em 2016, o projeto do Swagger foi renomeado para OpenAPI Specification e movido para um novo repositório do GitHub.

Configurando em projetos .Net Core

Para configurar em projetos .Net Core é relativamente simples, bastando apenas algumas instruções para começar a utiliza-lo.

Vamos aos passos:

1. Instalar as dependência no Nuget Package

Primeiramente você irá precisar importar ou instalar os pacotes do Swagger com NuGet package. Você pode abrir em seu projeto, clicando sobre o projeto com o botão direito e clicando na opção Manage NuGet Packages…, e irá abrir um gerenciador, como na figura abaixo:

Iremos buscar pelos pacotes Swashbuckle.AspNetCore.SwaggerGen e Swashbuckle.AspNetCore.SwaggerUI. Você pode instalar a versão mais recente possível, claro observando a compatibilidade com sua versão do .Net Core.

Outra forma de instalar estas dependências é pelo Package Manager Console, executando os comandos:

> Install-Package Swashbuckle.AspNetCore.SwaggerGen
> Install-Package Swashbuckle.AspNetCore.SwaggerUI

2. Fazer o setup da aplicação .Net Core para exibir a página do Swagger

2. Tendo instalado os pacotes, vamos configurar nossa aplicação .Net Core para expor a página do Swagger com todos os métodos de sua API.

Para isto, vamos modificar o nosso arquivos Startup.cs em dois trechos. Um nos serviços que são registrados e o outro, em nossa aplicação. Veja:

public void ConfigureServices(IServiceCollection services)
{
    //...

    services.AddSwaggerGen(c =>
    {
          c.EnableAnnotations();
          c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Application", Version = "v1" });
    });

    //...
}

E o outro trecho no método que configura a aplicação:

//...

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    app.UseSwagger();
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Application v1"));
}

//...

Com isto, já seria o suficiente para funcionar, mas tem um detalhe que pode deixar mais interessante ainda e que vamos configura que é a opção de abrir ao executar o projeto esta página do Swagger, que vou detalhar no próximo tópico.

3. Executar a página quando rodar o projeto

Configurar as opções de execução do projeto para abrir nesta página (em desenvolvimento). É muito importante falar, até mesmo por motivos óbvios, que isto não seja exposto em produção.

Vamos lá na pasta e arquivo Properties > launchSettings.json de nosso projeto de API, o que deve se assemelhar à imagem abaixo:

Ao abrir o arquivo, você terá diversas (acredito que mais de uma) ou apenas uma. Não tem problema, basta incluir as chaves na configuração que deseja executar. No meu caso, chamei de Api, como no trecho abaixo:

"Api": {
      "commandName": "Project",
      "dotnetRunMessages": "true",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },

Destaco as propriedades que irão fazer esta mágica que são a lauchUrl: “swagger” e lauchBrowser: true, para abrir já o browser com UI do Swagger.

Com isto, ele irá abrir a página já configurada com seus métodos, também muito semelhante com a imagem abaixo.

O Swagger é uma forma simples e muito útil para documentar sua aplicação. Na verdade, existem outras, mas para .Net Core eu não vejo a necessidade de explorar outros recursos, já que ela dá conta do trabalho.