Este artigo apresenta os conceitos principais no Apidog, uma ferramenta API-first concebida para um design, teste e colaboração eficientes de APIs. Muitos conceitos diferem de produtos semelhantes, como o Postman. Compreendê-los irá ajudá-lo a navegar eficazmente pelo fluxo de trabalho do Apidog.Projeto#
Um Projeto no Apidog é a unidade principal de colaboração, contendo módulos, ambientes, cenários de teste e muito mais. Serve como um contentor para todo o trabalho relacionado com APIs dentro de uma equipa.Componentes Principais de um Projeto#
Módulos: Agrupamentos lógicos de endpoints e componentes relacionados.
Ambientes: Conjuntos de variáveis para diferentes fases de implementação (por exemplo, desenvolvimento, staging, produção).
Cenários de Teste: Coleções de pedidos para testes automatizados.
Especificações de Endpoint: Documentação da API baseada nas normas OpenAPI/Swagger.
Comparação com o Postman#
| Conceito no Apidog | Equivalente no Postman | Descrição |
|---|
| Projeto | Workspace | Unidade organizacional de nível superior para colaboração. |
| Módulo | Collection Folder | Agrupa endpoints relacionados. |
| Equipa | Team | Funcionalidades de acesso partilhado e colaboração. |
Os projetos permitem uma colaboração fluida, possibilitando que vários utilizadores trabalhem em APIs simultaneamente, mantendo o controlo de versões e as permissões de acesso.
Módulo#
Um Módulo organiza endpoints de forma lógica dentro de um projeto, de modo semelhante a um "serviço" numa arquitetura de microsserviços. Cada módulo representa um ficheiro de especificação OpenAPI autónomo.Funcionalidades de um Módulo#
Contém endpoints, esquemas, respostas e esquemas de segurança relacionados.
Configurado com um URL Base por ambiente para geração automática de URLs.
Suporta operações de importação/exportação ao nível do módulo para uma melhor conformidade com normas.
Quando Utilizar Módulos#
Para microsserviços: cada serviço como um módulo separado.
Para várias APIs: agrupe endpoints por funcionalidade ou domínio.
Predefinição: novos projetos começam com um módulo; adicione mais conforme necessário para vários URLs base.
Os módulos alinham-se com a Especificação OpenAPI (OAS), facilitando a integração com outras ferramentas e mantendo limites de API bem definidos.
Endpoint#
Um Endpoint é o elemento central na abordagem API-first do Apidog, representando uma operação de API específica (por exemplo, GET /users/{id}).Gestão de Endpoints#
Agrupados em estruturas de diretórios para organização.
Ligado a casos de endpoint para exemplos de pedidos guardados.
Diferenças em relação ao Postman#
| Aspeto | Apidog (baseado em endpoints) | Postman (baseado em pedidos) |
|---|
| Unidade Básica | Endpoint (especificação da API) | Pedido (chamada individual) |
| Alterações à Especificação | Atualiza automaticamente casos e testes | Reescrita manual necessária |
| Estrutura | Extensão OAS com depuração | Especificações e pedidos separados |
No Apidog, as alterações às especificações de endpoints propagam-se automaticamente para todos os casos dependentes, reduzindo o esforço de manutenção através desta abordagem orientada por especificações.
Ambiente#
Um Ambiente gere variáveis e URLs base para diferentes contextos de implementação, permitindo alternar facilmente entre desenvolvimento, staging e produção.Funcionalidades Principais#
Contém variáveis de ambiente para valores dinâmicos.
Suporta vários URLs Base por ambiente para microsserviços. Construção automática de URL: URL Base + Caminho do Endpoint.
Exemplo de URL Base#
Suponha um projeto com três serviços:| Serviço | URL Base (Prod) | Caminho do Endpoint | URL Completo |
|---|
| Utilizador | https://user.example.com | GET /user/{id} | https://user.example.com/user/{id} |
| Encomenda | https://order.example.com | GET /order/{id} | https://order.example.com/order/{id} |
| Produto | https://product.example.com | GET /product/{id} | https://product.example.com/product/{id} |
Não há necessidade de marcadores de posição {{BaseUrl}} manuais; o Apidog deteta o módulo e aplica automaticamente o URL base correto.
Pedido#
Um Pedido é uma chamada de API autónoma, não associada a especificações de endpoint, semelhante aos pedidos do Postman.Capacidades de Pedido#
Criar independentemente das especificações. Analisar pedidos bem-sucedidos em especificações de endpoint. Utilizar para testes ad hoc ou APIs não documentadas.
Os pedidos oferecem flexibilidade para cenários em que as especificações da API não estão predefinidas, colmatando a lacuna entre fluxos de trabalho design-first e request-first.
Cenário de Teste#
Um Cenário de Teste executa lotes de pedidos, semelhante às Coleções do Postman, com funcionalidades avançadas de automatização.Funcionalidades#
Capacidades Avançadas#
Relatórios de teste e testes de desempenho.
Testes orientados por dados.
Os cenários de teste sincronizam automaticamente com as alterações à especificação da API, garantindo que os testes permanecem válidos à medida que as APIs evoluem.
Modo Design-first e Modo Request-first#
O módulo de APIs do Apidog inclui dois modos que podem ser alternados no canto inferior esquerdo da interface: Design-first Mode e Request-first Mode.Ambos os modos fornecem funcionalidades semelhantes, mas com interfaces diferentes, respondendo a diferentes fluxos de trabalho de equipas.Modo Design-first#
Recomendado para equipas que praticam primeiro o design da API.
Defina as especificações da API antes do desenvolvimento e dos testes.
Ideal para projetos planeados e orientados por especificações.
Modo Request-first#
Adequado para equipas que se concentram primeiro no desenvolvimento backend.
Crie pedidos e, em seguida, gere especificações a partir de chamadas bem-sucedidas.
Perfeito para APIs não documentadas ou integrações de terceiros.
Resumo#
Compreender estes conceitos principais irá ajudá-lo a tirar partido da abordagem API-first do Apidog para um design, teste e colaboração eficientes. Comece por criar um projeto, organize endpoints em módulos, defina ambientes para diferentes fases e crie cenários de teste para automatização.Para leitura adicional, explore as páginas de documentação ligadas ou experimente a interface do Apidog para ver estes conceitos em ação.
Pronto para Começar?#
Começar do Zero
Comece a utilizar o Apidog do zeroMigrar para o Apidog
Comece por migrar para o Apidog 