Criando API auto-documentável com Node.js e Swagger

fala Dev E aí beleza faz tempo que eu não gravo um vídeo aqui pro YouTube da Rocket City bom aos poucos quem sabe eu esteja voltando aqui para gravar mais conteúdo sobre react node e todas essas tecnologias afins e relacionadas tenho passado bastante tempo gravando conteúdo para algumas coisas que a gente vai liberar na Rocket City aí ao longo do final desse ano ao longo do início do ano que vem mas por enquanto ainda são segredos aí que eu venho trabalhando bastante junto com o time da Rocket eu tô aqui para quem sabe aos poucos né como eu falei a gente ir voltando Então já aqui nos comentários desse vídeo e coloca ah sugestões de conteúdo que eu possa trazer aí nos demais vídeos que aos poucos eu vou gravando para vocês mas ao longo desse tempo que eu fiquei meio off né eu trabalhei em muitos projetos pessoais ao longo além dos projetos da própria Rocket bom uma das coisas que eu fiz nesses projetos pessoais claro eu criei todo o projeto do zero tanto backend quanto frontend e eu percebi que no backend eu tô seguindo uma estrutura muito semelhante em todos esses projetos e em todos os projetos que eu tô criando agora eu tô usando algum conjunto de ferramentas que me permite criar um backend autod documentárista no backend quais é informações Você pode enviar parâmetros e ah o corpo da requisição Qual que é a resposta mas hoje eu vou falar especificamente sobre o backend claro utilizando node e utilizando o fast fy que é um dos frameworks que eu mais estou curtindo de utilizar ali dentro do node em si Já vamos direto aqui pro código né eu já tô aqui com o site do ffy aberto e eu criei uma pastinha aqui chamada backend tipado só pra gente construir juntos esse projetinho para eu te mostrar como é que funciona Tá eu vou abrir esse projetinho no no vest code e eu vou fazer aqui uma configuração do total zero aqui do projeto então eu vou começar rodando um pnpm init não precisa do menus Y aqui para criar o package P Jason e eu vou instalar basicamente esse conjunto de ferramentas aqui ó ah de bibliotecas Tá eu vou instalar o ffy ffi Type provider Zod né porque eu vou est utilizando o Zod para fazer a validação e também a documentação das minhas rotas né todos os dados que ela recebe todos os dados que ela devolve vou utilizar já o ffy cores né para permitir que esse backend seja acessado por algum um front end e o ZK é uma dependência do Fast F Type provider Além disso Claro para rodar o projeto a gente vai precisar de algumas dependências de desenvolvimento que nesse caso vai ser o typ script o types node e o tsx também que é o pacote que vai permitir a gente executar o projeto sem precisar fazer a a transpilation ali do código E aí aqui no package P json eu vou basicamente apenas criar um script e vou jogar aqui tsx passando aqui search server. ts que vai tá que vai ser o caminho Além disso vou rodar aqui o tsc init para ele criar o arquivo TS config né que o meu aqui eu deixei ele com collapse então ele tá aqui dentro do package p json e aqui ó no node eu tô usando a versão 20 do node tá ela não é a versão mais recente LTS Mas você pode utilizar a versão que você preferir E aí no TS config bases aqui que é o repositório da Microsoft com as configurações do test config eu vou basicamente aqui no node 20 copiar como que deve ser o padrão do test config no node 20 então beleza copiado aqui já posso sair codando a minha aplicação não tem mais o que configurar eu vou direto criar agora o meu arquivo server que fica dentro da pasta sece né então search barver PTS e eu vou sair importando os pacotes tá eu gosto sempre de fazer Import nomeado então eu não gosto de fazer Import default todos os pacotes do fesf eles exportam também de forma nomeada Então posso usar Chaves aqui para importar Então posso até digitar parte do pacote aqui ó ele já dá a opção de fazer importação aí eu só venho aqui e altero caso ele não tenha entendido que eu quero um Import nomeado e aqui agora eu vou criar a minha aplicação posso chamar de App posso chamar de server Geralmente eu acabo chamando ela de app E aí no final eu faço essa aplicação aqui ouvir a porta 3333 E aí quando terminar de ouvir essa porta eu vou dar um http server Running pra gente saber que o servidor tá rodando e aqui eu vou ter algumas rotas da minha aplicação mas antes eu vou registrar aqui O plugin do corse e por padrão eu vou liberar ele para todas as origens Ou seja todos os endereços de frontend poderem acessar essa esse meu backend né e agora além disso eu vou configurar o fast fy Type provider Zod tá E aí no Fast fy Type provider Zod aqui a gente tem algumas coisas que a gente tem que configurar primeiro eu tenho que importar o validator compiler e o o serializer compiler que que esses dois carinhas fazem aqui né a gente vai usar o Zod aqui para duas coisas primeiro delas validação então aqui no app eu dou um set validator compiler e passo o validator compiler que vem daqui de dentro a partir desse momento o FF já sabe que eu vou estar utilizando o Zod para fazer a validação de todos os dados de entrada e aí eu também vou dar um set serializer compiler passando aqui o meu serializer compiler falando pro ffy que eu vou utilizar também o Zod para fazer a transformação né a serialização dos dados de saída ou seja os dados que eu devolvo das rotas para o meu front end feito isso a última coisa que a gente vai fazer aqui dentro é configurar aqui algumas rotas e também configurar o fast fy Swagger né o Swagger que hoje é a ferramenta aí mais convencional no backend pra gente fazer a documentação dos nossos backends né das rotas do nosso backend da nossa api Então vou instalar tanto pacote @f Swagger quanto swager ui vou fazer a instalação desses dois pacotes aqui vou aguardar rapidinho ele fazer a instalação e eu já vou instalar né registrar esses dois pacotes aqui então primeiro Fast F Swagger e aqui uma dicazinha tá vendo que na importação ele sempre tem o roxinho e o azul no vest code o azul é sempre o named Export e o roxo É sempre o module Né que é o Export default então não gosto de usar muito Export P default então eu mantenho dessa forma aqui no Fast F swager aqui eu vou passar Open api vou passar info E aí eu passo o título da minha api Vou botar aqui typed api e vou passar uma versão da api 1. 0.

0 veja que aqui eu tô usando o padrão Open api Existem várias especificações né o Swagger ele tem suporte tanto pra especificação no formato Swagger e no formato Open api que também tem as suas versões eu vou usar o open api porque ele tem suporte algumas coisas que o swager que a especificação Swagger não tem E aí eu vou registrar aqui também Fast F Swagger e e vou passar aqui um Road prefix doc isso quer dizer que quando eu acessar a rota bar doc eu vou ter acesso à documentação da minha api salvo isso aqui agora vou registrar aqui agora uma rota bem simples que é só um hello world salvo aqui agora e rodo o meu projeto projeto rodando agora se eu vier aqui no meu navegador e abrir local rosto 3333 bar dox veja eu já tenho o swager aqui dentro e veja que ele não conseguiu encontrar nenhuma operação definida na minha documentação e isso porque quando eu estou utilizando swager eu preciso adicionar algumas é informações nas minhas rotas para fazer com que elas estejam disponíveis aqui na minha documentação Mas que que eu vou fazer aqui eu vou criar um arquivo separado de Rota Só pra gente não deixar tudo num arquivo só e esse arquivo de rotas ele vai ser bem simples Tá eu vou exportar como uma default async function default não né Só uma ayn function rootes mesmo eu vou receber o app instance e aqui eu vou criar as minhas rotas por exemplo uma rota de listar tagem de usuários logo eu já vou realmente listar esse usuários né Por enquanto ela não vai retornar nada e aí aqui dentro eu posso vir dar um app. register rootes aqui no meu arquivo de rotas e pronto servidor continua funcionando outra coisa aqui no package P Jason vou botar um watch aqui no tsx assim quando eu altero os arquivos ele já roda de novo né como se fosse o nodemon ali ou o Watch do próprio node E aí aqui nas rotas da minha aplicação veja que eu tô recebendo ffy instance né que ele é a Instância do Fast fy Nativa só que o que acontece como eu tô usando o Zod né o ffy Type provider Z o que acontece é se eu venho aqui e passo um parâmetro é como segundo parâmetro aqui do app. get aqui dentro Eu tenho uma série de configurações que eu posso fazer e uma delas é o esima que é basicamente Qual que é o formato né de entrada e saída de dados que vai servir como documentação E também como validação dos dados aqui se eu colocar bar por exemplo né É claro que na listagem de usuários a gente não vai ter bar né Então deixa eu até vir aqui tirar isso aqui criar uma rota app.

poost users E aí sim eu vou botar aqui dentro como se fosse a criação de um usuário e aí aqui dentro eu vou colocar o meu esquema para validar o meu bar nesse caso aqui do meu bar veja que se eu tentar passar um o Zod por mais que ele funcione vamos falar aqui que ele precisa do do nome né quando eu venho aqui na minha documentação veja que agora já tem as duas rotas né get users e já tenho aqui a post users né pra criação do usuário e veja que aqui no bar Ó ó ele fala que ele pode receber um uma string e o skima ó tá vazio não tem não tem nada isso Por quê né porque por padrão ele não vai com conseguir entender que o Zod né ele vai tá sendo utilizado aqui para fazer a validação do input de dados Então a gente tem que fazer algumas e alterações aqui primeira delas né que eu vou fazer aqui no Fast fy eu vou dar um with Type provider aqui em cima e eu vou botar aqui Zod Type provider Além disso eu vou criar um arquivo de types aqui e eu vou exportar um Type chamado fast fy typed instance onde eu vou pegar o ffy instance padrão do próprio Fast fy que é o que eu tô usando aqui ó só que eu vou passar alguns generics para ele só que como eu só quero passar alguns Alguns desses generics eu quero usar os próprios do ffy então se eu passar o mouse aqui eu posso ver que o primeiro generic que ele recebe é esse Raw server default Então vou manter ele porque eu não quero mexer no server do ffy o segundo é o Raw request default Expression Então a gente vai passar aqui o último é o o próximo é o Raw reply default Expression que eu vou ter que importar tudo isso aqui ali de dentro do Fast fy o próximo é o logger que é o fast fy base logger também não vou modificar só que se a gente for ver o último é o Type provider que ele usa o padrão do ffy ffy Type provider nesse caso aqui eu vou trocar pro Zod Type provider que vem lá do Fast fy Type provider Zod e agora eu vou trocar aqui por Fast fy typed instance que eu acabei de criar e eu não preciso mais importar agora do Fast fy e agora ele já entende que automaticamente quando eu passar por exemplo aqui o bar né que antes era que que ele deixava eu passar qualquer coisa agora eu posso usar o Zod para fazer essa validação só que aqui eu vou adicionar mais algumas outras coisas por exemplo uma descrição Create a new user vou adicionar uma tag que é uma maneira da gente agrupar as rotas ali dentro do swager então tanto a rota de listagem de usuários quanto a de criação de usuários eu vou agrupar dentro dessa tag users aqui e aqui eu vou botar uma descrição ah list users e aqui no bar para criar um usuário eu vou falar que ele pode receber um nome e pode receber um e-mail e o e-mail vou fazer uma validação aqui se ele é um e-mail válido E aí uma das coisas legais é que se eu venho aqui ó do ffy pego o bar veja que agora dentro do bar eu já tenho o nome e e-mail aqui do usuário e eu posso fazer o que eu quiser com isso então por exemplo se eu criar aqui em cima uma interface user falando que meus usuários vão ter ID vão ter nome vão ter e-mail Quando eu for vou criar uma rede de usuários aqui simulando meu banco de dados quando eu for criar um usuário eu vou simplesmente dar users P push vou criar um ID aqui posso usar o Random o ID que vem do crypto né Deixa eu só adicionar um prefixo node aqui na frente e vou adicionar também o nome e o e-mail aqui deste usuário e no final aqui eu posso devolver algo posso não devolver nada eu vou devolver aqui reply pon status 2001 que geralmente é o código que a gente usa quando criou alguma coisa e vou dar um send vazio aqui dentro se eu salvar isso aqui agora e aqui eu vou falar que users tem que seguir esse formato aqui né voltando aqui na minha documentação veja que aqui dentro de post o esima ele ainda não conseguiu entender no swager que eu vou usar o Zod isso porque aqui no meu server. ts aqui embaixo ó eu preciso passar ah Transform E aí eu vou Vou importar de dentro do Fast Fight Type providers Zod o Jason schema Transform salvando isso aqui agora vindo aqui reiniciando o meu servidor olha só ele já entendeu que a minha rota agora de criação de um usuário recebe nome e e-mail Obrigatoriamente se eu vi aqui em esima ó ele já fala né nome e-mail que nenhuma informação é opcional E aí a gente consegue testar Inclusive essa rota aqui por dentro então se eu vir aqui em Try It Out né vira aqui e preencher por exemplo John do e vou deixar user @example. com mesmoo dou um Execute veja deu certo né Ele retornou aqui 201 e veja que ele falou undocumented ou seja ele devolveu uma resposta que não é documentada e eu tenho que documentar ela is é bem importante se eu vier aqui na listagem de usuários né ó ele não fala ele não tem documentação nenhuma mas eu posso também testar dar um Execute e veja que ele traz aqui os meus dados ele não trouxe os usuários porque aqui ó eu tô retornando sempre um arrei vazio né eu poderia retornar users dessa forma só que agora a gente vai continuar adicionando um pouco mais de documentação nessas rotas então por exemplo aqui na lista na criação de usuários eu posso posso documentar as as respostas então na resposta eu documento sempre por código então quando essa rota devolveu o código 201 que é o código de criação ela não vai ter retorno então eu posso botar aqui z.

nulo por exemplo e botar aqui um um describe para falar user created né para indicar que isso aqui é a resposta de sucesso né para dizer que ele foi realmente criado e aqui ele já começa a dar erro né Por quê Porque eu falo aqui eu acho que é porque aqui precisa ser uma assn não é exato porque o handler precisa ser uma async function e aqui nos usuários vários ó na listagem a gente não recebe nenhum parâmetro mas a minha resposta 200 que é o padrão ela devolve um Array de objetos e esses objetos T ID nome e e-mail e aqui no e-mail eu só boto string veja que eu não preciso botar e-mail dessa forma por quê Porque eu não preciso validar a saída né Eu só preciso garantir que ela existe não preciso fazer uma validação nemuma transformação do dado porque o e-mail só preciso validar na entrada né e não na saída dos dados dou F5 aqui agora e veja que a minha rota né de listagem aqui dos users ó agora ela já tem um example value tá vendo aqui ó ID nome e-mail né com esquema também para saber exatamente quais dados ela retorna e aqui na criação do usuário eu já tenho documentado o código 201 e que ele não retorna nada né então a gente pode fazer mais um teste aqui dentro vou dar um Execute veja Ele criou e agora o 201 não tá mais mostrando que ele não tá não documentado digamos assim posso dar um Try It Out na listagem e veja ele já fez a listagem com código 200 e trouxe aqui o meu usuário isso aqui é um pouco do que que eu venho fazendo em quase todos os meus projetos node né Hoje quase toda api que eu crio com node Independente de arquitetura é eu tô usando fastfire eu tô usando esse modelo de E é claro um pouco mais trabalhado do que isso mas assim basicamente ffy com essa integração com o fast F Type provider Zod né a gente teve versão 5. 0 do Fast fy aí e recentemente e lançou muita coisa nova né Eu acho que diferente do Express que lançou agora acho que foi agora pouco né E aqui tanto faz né comparar eu acho que é independe a a tecnologia que tu tiver utilizando mas ffi lançou Ou nem lançou ainda a versão 5. 0 é lançou a versão 5.

0 acho que isso aqui saiu depois de sei lá quantos anos sem atualizações então assim eu aqui ó Express 5.