Skip to main content

Swagger

Descrição Técnica do Back-End

 

O backend do projeto é estruturado de forma modular, com separação clara de responsabilidades entre rotas, controllers, middlewares e utilitários. A aplicação é desenvolvida utilizando Node.js com Express e toda a API está documentada de forma interativa utilizando o Swagger UI, acessível pelo endereço: 

http://localhost:${PORT}/api/v1/swagger onde PORT é definida pela variável de ambiente API_PORT ou assume o valor padrão 3006.

Lembre-se de ter o projeto rodando no docker para funcionar!

Estrutura de Pastas:Diretórios:

/api/
├── src/
│   ├── controller/        # 🎮 Controladores responsáveis pela lógica de cada domínio.
│   │   ├── otp/              # Envio de OTPs e recuperação de senha
│   │   ├── patrimonio/
│   │   ├── setor/
│   │   ├── usuario/
│
│   ├── docs/               # 📄📘 ConfiguraçõesScripts de geração e definiçde documentação dosSwagger.
endpoints│   no│   Swagger└── compare-docs.ts
│   │   └── generate-docs.ts
│   │   └── swagger.ts
│   │   └── swaggerSchemas.ts
│   
│   ├── middlewares/       # ⚙️ Middlewares diversos, incluindo o multer para uploads
│   │   └├── multer.tsauthFacade/
│   │   ├── basicAuth/
│   │   ├── checkSetor/
│   │   ├── multer/
│   
│   ├── router/             # 🛣️ Definição de todas as rotas do sistema organizadas por domínio
│   │   ├── avaliador/otp/
│   │   ├── corregedor/patrimonio/
│   │   ├── defensor/setor/
│   │   ├── usuario/
│   │   └── router.ts       # Roteador principal que importa e agrupa os módulos acima
│
│   ├── services/utils/              # 🧩🧰 RegrasFunções de negócioauxiliares e funcionalidadesutilitários para cada tipo de usuárioreutilizáveis.
│   │   ├── avaliador/administrador/
│   │   ├── corregedor/email/
│   │   ├── defensor/otp/                │# │gerar └── usuario/OTP
│   │   ├── utils/              # 🔧 Utilitários de suporte à aplicaçãoqrcode/
│   │   ├── opt/            # Envio de OTPs e recuperação de senha
│   │   ├── pdf/            # Operações de manipulação e leitura de PDFstypes/
│   │   ├── validations/        # Validaçõesão como token, CPF, e campos diversoscpf
│   │   └── ...expirarSetor.ts     # OutrosValidação utilitáriosde adicionaisexpiração do setor
│
│   └── app.tsxts         # 🎯 Ponto de entrada da aplicação e inicialização dos serviços

Documentação Interativa com Swagger

A API conta com documentação completa utilizando Swagger, onde é possível:

  • Visualizar todos os endpoints disponíveis

  • Ver os parâmetros esperados por cada rota

  • Testar requisições diretamente pela interface

  • Visualizar exemplos de respostas de sucesso e erro

Exemplo de rotas documentadas:

  • POST /api/v1/patrimonio/cadastrar
    permite que um usuário com a devida permissão cadastre um novo patrimônio no sistema.

  • PUT /api/v1/patrimonio/editar

    Permite que um usuário com a devida permissão edite um patrimônio.

  • GET /api/v1/usuario/buscar
    Retorna os usuários cadastrados.

  • POST /api/v1/setor/cadastrar
    Permite ao usuário com a devida permissão cadastrar um novo setor no sistema.

Essas e outras rotas estão organizadas por grupos lógicos (Patrimônio, Usuário, Setor) dentro do Swagger UI.

Upload de Arquivos com Multer

A aplicação utiliza o middleware Multer para lidar com uploads de arquivos (como csv), salvando-os em diretórios específicos com nomes padronizados conforme o campo da requisição.

 

Back to top