Em um projeto Apidog, os endpoints são gerenciados em uma estrutura hierárquica de Módulo → Pasta → Endpoints.
- Módulos representam arquivos OpenAPI independentes, geralmente agrupados por domínio de negócio ou serviço.
- Pastas organizam os endpoints por funcionalidade ou função dentro de um módulo.
- Endpoints são as especificações OpenAPI ou definições de API reais.
Compreender essa estrutura é fundamental para organizar suas APIs de forma eficiente.
Aqui está um exemplo de hierarquia simples:
Projeto Apidog
│
├── Módulo: Serviço de Usuário (dividido por domínio de negócio ou serviço)
│ │
│ ├── Pasta: Autenticação de Usuário (categoria de funcionalidade)
│ │ │
│ │ ├── Endpoint: POST /login (Login)
│ │ └── Endpoint: POST /register (Registrar)
│ │
│ └── Pasta: Informações do Usuário
│ │
│ └── Endpoint: GET /users/{id} (Obter Informações do Usuário)
│
└── Módulo: Serviço de Pedidos
│
├── Pasta: Gerenciamento de Pedidos
│ │
│ ├── Endpoint: POST /orders (Criar Pedido)
│ └── Endpoint: GET /orders/{id} (Obter Detalhes do Pedido)
│
└── Pasta: Pagamento
│
└── Endpoint: POST /payment/submit (Enviar Pagamento)Entendendo os Módulos no Apidog
Depois de entender a hierarquia do projeto, a próxima pergunta é: Todo projeto precisa de módulos? Quando você deve criar um novo?
Ao criar um novo projeto, o Apidog gera automaticamente um módulo padrão. Se o seu projeto contém apenas um único serviço de backend ou um pequeno conjunto de endpoints, esse módulo padrão geralmente é suficiente. No entanto, se você precisar gerenciar vários serviços de API distintos, pode criar um módulo separado para cada um.
Por exemplo, um backend de projeto pode incluir serviços como Usuário, Produto, Pedido e Logística — cada um responsável por um domínio específico e frequentemente implantado em diferentes URLs de serviço. Nesse caso, é recomendável criar módulos individuais para esses serviços para gerenciar seus endpoints de forma independente.
Você pode criar um módulo clicando no botão + acima da árvore de pastas e selecionando Módulo.
Uma vez criado, ele aparece na árvore de projetos à esquerda junto com os outros, com seu próprio espaço para pastas e endpoints. Você pode adicionar livremente endpoints e pastas dentro de cada módulo.
Os módulos são independentes uns dos outros, cada um com seus próprios endpoints, esquemas, componentes e variáveis de módulo. No entanto, os esquemas podem ser referenciados entre módulos. Além disso, as configurações de nível de projeto, como variáveis de ambiente, conexões de banco de dados e scripts comuns, são acessíveis a todos os módulos.
Cada módulo corresponde a um arquivo de especificação OpenAPI completo. Ao exportar seu projeto, os arquivos OpenAPI são gerados por módulo.
Entendendo as Pastas dentro de um Módulo
Depois de criar seus módulos, o próximo passo é planejar como estruturar os endpoints dentro deles.
Cada módulo começa com uma pasta raiz que contém todas as subpastas e endpoints.
Você pode criar pastas diretamente sob a raiz ou aninhá-las dentro de outras pastas existentes.
Ao projetar a estrutura de pastas, considere a complexidade do módulo. Para um módulo com apenas alguns endpoints, uma pasta simples de nível único organizada por função geralmente é suficiente. Mas para módulos mais complexos, é melhor criar pastas multi-nível bem estruturadas para manter tudo organizado e fácil de navegar.
Por exemplo, em um módulo de Serviço de Usuário, você pode ter pastas de nível superior, como:
- Autenticação de Usuário (para endpoints de login, registro, redefinição de senha)
- Informações do Usuário
- Controle de Acesso
Se uma pasta se tornar muito grande ou logicamente independente, você pode convertê-la em um módulo autônomo.
Clique no ícone ... ao lado do nome da pasta e selecione ...Mais > Converter para um novo Módulo. Isso ajuda a manter a estrutura do seu projeto bem organizada à medida que ele escala.
Gerenciamento de Ambiente e Configuração para um Módulo
Além dos endpoints estruturados, cada módulo geralmente corresponde a um endereço de serviço ou ambiente de implantação diferente. Você pode configurá-los facilmente no Gerenciamento de Ambiente.
Nas configurações de gerenciamento de ambiente, a URL Base de cada módulo pode ser configurada separadamente. Por exemplo, em um Ambiente de Teste:
- Serviço de Usuário →
http://user-service:8001 - Serviço de Pedidos →
http://order-service:8002
Ao alternar ambientes, o Apidog atualiza automaticamente a URL base de cada módulo. Por exemplo, ao alternar do ambiente de desenvolvimento para o de teste, a URL base do módulo de serviço de usuário mudará de http://localhost:8001 para http://user-service:8001, e a URL base do módulo de serviço de pedidos mudará de http://localhost:8002 para http://order-service:8002.
As variáveis de ambiente são compartilhadas entre todos os módulos e funcionam melhor para armazenar configurações que diferem entre ambientes. Em contraste, as variáveis de módulo são exclusivas de cada módulo — por exemplo, suas próprias chaves de API ou tokens — e podem ser usadas em qualquer endpoint dentro desse módulo.
Gerenciando e Reutilizando Esquemas
O gerenciamento eficiente de esquemas ajuda a evitar duplicação e garante a consistência entre os módulos.
Cada módulo tem sua própria seção de gerenciamento de esquemas, onde você pode definir e manter estruturas de dados relacionadas ao negócio. Esses esquemas podem ser reutilizados dentro do módulo ou referenciados por outros.
Por exemplo, o módulo de Serviço de Usuário define esquemas relacionados ao usuário. O módulo de Serviço de Pedidos define esquemas relacionados a pedidos. Se o Serviço de Pedidos precisar referenciar informações do usuário, ele pode simplesmente reutilizar o esquema do Serviço de Usuário — sem a necessidade de recriá-lo.
Do Postman para o Apidog: Organizando Coleções e Endpoints Importados
Se sua equipe usava o Postman anteriormente, você pode facilmente migrar coleções e endpoints existentes para o Apidog.
Durante a importação:
- Cada Coleção Postman se torna um Módulo.
- As estruturas de pastas são mapeadas automaticamente.
- Endpoints e esquemas são preservados.
Isso permite que você mantenha sua estrutura de API familiar enquanto aproveita o sistema modular do Apidog.
Conclusão
Ao definir módulos claros, organizar pastas e reutilizar esquemas, você pode manter seus projetos Apidog limpos, escaláveis e fáceis de colaborar.
O design modular do Apidog ajuda as equipes a trabalhar mais rápido, evitar confusão e gerenciar APIs complexas de forma mais eficiente — do design à documentação e aos testes.