.NET + Swagger + OpenAPI +ReDoc

Veja nesse artigo o que é o Redoc e como adicionar ele em um projeto .NET API

Introdução

O Swagger é um framework composto por diversas ferramentas que, independente da linguagem, auxilia a descrição, consumo e visualização de serviços de uma API REST. Através dele nós podemos ver os endpoints, dados recebidos, dados retornados, métodos de autenticação, entre outros dados referente a uma API.

Quase sinônimo do Swagger, OpenAPI é uma série de especificações definidas pela comunidade em conjunto com a Open API Iniciative, para descrição e documentação de API’s.

Totalmente independente de uma linguagem de programação, a especificação OpenAPI permite que tanto humanos quanto aplicações, compreendam e explorem um serviço sem necessitar ter acesso ao seu código fonte.

O Redoc é uma ferramenta de código aberto para geração de documentação com base nas definições do OpenAPI. Utilizando esta ferramenta, nós podemos retornar para os nossos usuários uma documentação completa com texto (descrição de cada ação) e uma parte de teste como nós temos com o Swagger.

Agora que sabemos o que é o Redoc, o foco deste artigo será demonstrar como utilizar ele para documentar a sua API .NET.

Parte prática

Crie um novo projeto .NET na sua máquina, em seguida adicione a seguinte biblioteca nele:

dotnet add package Swashbuckle.AspNetCore.ReDoc

Agora adicione o app.UseReDoc() dentro do arquivo Program.cs, conforme o exemplo a seguir:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();

    app.UseReDoc(c =>
  {
      c.DocumentTitle = "REDOC API Documentation";
      c.SpecUrl = "/swagger/v1/swagger.json";
  });
}

Execute o seu projeto, em seguida abra o endereço localhost:{porta}/api-docs no seu navegador. A seguir você tem um print demonstrando este passo:

Bem legal né?

Mas este exemplo esta muito simples, que tal criar um exemplo mais completo, demonstrando como podemos utilizar esta biblioteca para documentar os nossos projeto?

Para pular a etapa de criação de muitos arquivos “que não é a proposta deste artigo”, estou disponibilizando o link de um projeto no meu GitHub, que foi desenvolvido para este artigo: dotnet-redoc.

Nesse projeto nós temos:

• Uma controller chamada NoticiasController com alguns métodos: Get, GetNews, Create, Update e Delete. Note que todos métodos tem um Summary com uma breve descrição do método e de seus parametros;
• Uma Entidade chamada Noticia, com duas propriedades: Id e Title;
• Uma Interface chamada INewsService, para que possamos simular o CRUD.

E no arquivo Program.cs, nós temos as seguintes alterações:

• Dentro de builder.Services.AddSwaggerGen(), nós adicionamos algumas informações básicas referente ao projeto como: Imagem de logo, nome do desenvolvedor, e-mail, descrição rápida do projeto…etc;
• Removemos o IF de development, para que possamos subir a Doc em um server.

Agora para que você possa ter uma live demo deste código funcionando, eu publiquei ele no Render.

Caso tenha interesse em saber como publicar os seus projetos no Render, eu recomendo a leitura do seguinte artigo: [Dica rápida] Herbs + Render

Abra a url dotnet-render no seu navegador, em seguida, navegue pela documentação do projeto demonstrado neste artigo.

Exemplo .NET Swagger e Redoc

Bom, era isso que eu queria passar para vocês pessoal, espero que tenham gostado e até um próximo artigo :)