ASP.NET Core + Swagger: Adicionando header parameter na sua documentação
Saiba como inserir o header da sua requisição utilizando o swagger, e documente sua aplicação REST de forma elegante.
Quando lidamos com aplicações que possuam autenticação baseadas em token, é comum que lidemos com esses tokens sendo passados no header das nossas requisições. Quando estamos trabalhando com swagger e queremos documentar nossa aplicação da melhor maneira possível, não queremos ter que utilizar o Postman, exemplo, apenas porque temos que inserir valores em nosso header, por isso, vamos permitir que o swagger aceite valores no header de nossas requisições.
O que preciso?
Visual Studio 2017 — Contendo .NET Core 2.0 e .NET Framework 4.6.2
Swashbuckle (Swagger para Web Api) — https://github.com/domaindrivendev/Swashbuckle
Disposição (Se já chegou até aqui, você já tem e muita!)
Por onde começo?
Para este projeto de exemplo, utilizarei o template padrão Web API (ASP.NET Core 2.0) do próprio Visual Studio 2017, seguindo a seguinte estrutura:
Agora iremos criar um filtro personalizado que passará nosso token ou qualquer valor, através do header. Criarei uma pasta na solução chamada “Filters” onde conterá nossa classe de header. Criaremos a classe “AddRequiredHeaderParameter” e implementaremos a interface IOperationFilter do próprio swashbuckle, como podemos ver nela conseguimos inserir o parâmetro de acordo com a nossa necessidade, no nosso caso, precisamos do header:
Na nossa classe Startup, iremos adicionar à nossa configuração do swagger, nosso filtro personalizado:
Na nossa controller só iremos retornar o token que está sendo passado no header da chamada, para nos certificarmos que o nosso filtro funcionou:
1, 2, 3, Testando!
Vamos inserir um token gerado automaticamente e de forma aleatória e conferir o resultado para ver se foi tudo de acordo:
Conclusão
Swagger é uma ferramento espetacular para documentação de serviços, e saber documentar cada parte dele é essencial. Espero que com esse breve artigo, você seja capaz de implementar parâmetros do header da sua request de suas Web APIs.
