Muitos já devem conhecer o Swagger como solução principal na hora de documentar sua API utilizando o framework .NET CORE, mas recentemente andei pesquisando uma alternativa mais Sofisticada para apresentar a API que estou trabalhando, e um colega me falou sobre o Redoc.
Neste artigo, mostrarei os primeiros passos que usei para implementar essa ferramenta muito eficiente – e bem mais a frente do Swagger no quesito UI. No final, também disponibilizarei o reposítorio do Redoc caso você queira se aprofundar na documentação.
Apresentação
Abaixo, a imagem que demonstra como ficará sua API após a implementação do Redoc, note que a imagem representa o resultado de uma instalação simples, podendo mais tarde o desenvolvedor configurar conforme seu gosto, inclusive adicionar CSS customizado, como cita na documentação do projeto.
Instalação
Antes da instalação do Redoc, você precisa configurar seu projeto para gerar o XML de documentação e configurar também o Swashbuckle para gerar o JSON responsável pela montagem da interface, com isso você pode alternar entre o swagger e o redoc ou manter ambos em funcionamento.
- Gerando XML com a documentação
- No projeto onde estão seus controllers, se estiver utilizando o Visual Studio, clique com o botão direito e vá em propriedades, logo após isso, clique na aba build e marque a opção XML Documentation File, conforme mostra a imagem abaixo.
- Salve e feche o arquivo.
2. Configurando Swashbuckle para Gerar o JSON
- Instale a versão mais recente do Swashbuckle no projeto que contenha sua classe Startup.cs
- Neste Site você encontra o projeto disponível para ser baixado do Nuget. Veja também se seu framework .NET CORE possue os requisítos de dependência.
- Copie o código abaixo e coloque no método ConfigureServices da classe Startup.cs, ele será responsável por gerar a documentação a partir do XML que a gente configurou utilizando o caminho do arquivo relativamente.
- Utilize o assembly: using Swashbuckle.AspNetCore.Swagger;
- Caso esteja em dúvida aonde colocar o código, aconselho deixar sempre no final do método.
3. Instalando o Redoc
- Instale a versão mais recente do Redoc no projeto que contenha sua classe Startup.cs
- Neste Site você encontra o projeto disponível para ser baixado do Nuget. Veja também se seu framework .NET CORE possue os requisítos de dependência.
- Cole o código abaixo no método Configure da classe Startup.cs sempre antes da chamada de método app.UseMvc();
- Não utilize o app.UseSwaggerUI caso queira somente que o Redoc funcione como ferramenta de documentação, caso queira que o Swagger também funcione em paralelo, então mantenha esse método.
- Finalizada as instruções de instalação, agora você poderá documentar suas Actions, como o exemplo abaixo. Para mais detalhes, dê uma olhada nas referências.
Redoc VS Swagger
É bem notável o ganho de estilo que sua documentação obtém com o Redoc, mas ele também possui algumas desvantagens em relação ao Swagger, e que até o momento, não encontrei nenhuma solução para esses pequenos problemas, por isso sintam-se à vontade para sugerir melhorias caso saibam de algo.
- As Actions dos seus controllers não podem ter o mesmo nome, pois causa uma confusão na hora da seleção quando você está navegando entre elas na interface.
- Não é possível realizar Testes através da interface, como disponibiliza o Swagger.