Opções da CLI do Apidog

A CLI do Apidog é utilizada para executar testes automatizados e gerir recursos de projetos do Apidog a partir de um terminal ou pipeline de CI/CD. Suporta execução de testes, gestão de recursos de design de API, ambientes e variáveis, importação e exportação, publicação de documentação, colaboração em branches e administração de projetos.

Sintaxe Básica da CLI do Apidog

A maioria dos comandos de recursos de projeto utiliza --project <projectId> para especificar o projeto. Pode utilizar --branch <branchName> para operar numa branch específica. Se --branch for omitido, o servidor utiliza a branch predefinida.

Autenticação

Antes de aceder a projetos privados, inicie sessão ou forneça um token de acesso.

Comando	Descrição	Exemplo
`login`	Inicia sessão com um token de acesso e guarda-o localmente.	`apidog login --with-token <token>`
`logout`	Termina a sessão e limpa o token local guardado.	`apidog logout`
`whoami`	Mostra informações sobre o utilizador autenticado atual.	`apidog whoami`

Também pode passar um token diretamente ao executar comandos:

Se estiver a utilizar GitHub Actions, pode armazenar o seu token de acesso em Settings --> Secrets and Variables --> Actions --> Repository variables do seu repositório. Em seguida, utilize ${{ vars.APIDOG_ACCESS_TOKEN }} para o referenciar.

Esquema da CLI

Utilize cli-schema para inspecionar e validar ficheiros JSON antes de criar ou atualizar recursos complexos. Isto ajuda a reduzir falhas de pedidos causadas por dados malformados.

Comando	Descrição	Exemplo
`cli-schema list`	Lista todas as chaves de esquema suportadas pela CLI.	`apidog cli-schema list`
`cli-schema get`	Imprime o JSON Schema para um ficheiro de dados de comando.	`apidog cli-schema get endpoint-create`
`cli-schema validate`	Valida um ficheiro JSON local em relação a uma chave de esquema.	`apidog cli-schema validate endpoint-create --file ./endpoint.json`

As chaves de esquema normalmente combinam o caminho do comando e a ação, como endpoint-create, test-scenario-update e merge-request-create.

Equipas e Projetos

Os comandos de equipa e projeto são o ponto de partida para gerir recursos através da CLI. Utilize-os para encontrar os IDs exigidos pelos comandos ao nível do projeto.

Gestão de Equipas

Comando	Descrição	Exemplo
`team list`	Lista as equipas acessíveis à conta atual.	`apidog team list`
`team get`	Consulta os detalhes de uma equipa específica.	`apidog team get <teamId>`

Gestão de Projetos

Comando	Descrição	Exemplo
`project list`	Lista os projetos acessíveis à conta atual.	`apidog project list`
`project get`	Consulta os detalhes do projeto.	`apidog project get <projectId>`
`project create`	Cria um projeto numa equipa.	`apidog project create --team <teamId> --name "New Project"`

Definições do Projeto

Comando	Descrição	Exemplo
`project settings get`	Consulta as definições ao nível do projeto.	`apidog project settings get --project <projectId>`
`project settings update`	Atualiza as definições do projeto com um ficheiro JSON.	`apidog project settings update --project <projectId> --file ./project-settings.json`
`cli-schema get project-settings-update`	Consulta o esquema para atualizações das definições do projeto.	`apidog cli-schema get project-settings-update`

Ambientes e Variáveis

Utilize estes comandos para gerir ambientes de execução, variáveis globais e variáveis de equipa utilizadas pela depuração de API e por testes automatizados.

Gestão de Ambientes

Comando	Descrição	Exemplo
`environment list`	Lista ambientes num projeto.	`apidog environment list --project <projectId>`
`environment get`	Consulta detalhes do ambiente, como URLs base.	`apidog environment get <environmentId> --project <projectId>`
`environment create`	Cria um ambiente.	`apidog environment create <name> --project <projectId> --base-url <url>`
`environment update`	Atualiza um ambiente.	`apidog environment update <environmentId> --project <projectId> --file ./environment.json`
`environment delete`	Elimina um ambiente.	`apidog environment delete <environmentId> --project <projectId>`
`cli-schema get environment-update`	Consulta o esquema para atualizações de ambiente.	`apidog cli-schema get environment-update`

Gestão de Variáveis

Comando	Descrição	Exemplo
`variables list`	Lista variáveis por âmbito.	`apidog variables list --project <projectId> --scope global`
`variables get`	Consulta o valor de uma variável.	`apidog variables get --project <projectId> --scope global --key <key>`
`variables set`	Cria ou atualiza uma variável.	`apidog variables set --project <projectId> --scope global --key <key> --value <value>`
`variables delete`	Elimina uma variável.	`apidog variables delete --project <projectId> --scope global --key <key>`
`variables import`	Importa variáveis a partir de um ficheiro local.	`apidog variables import --project <projectId> --scope global --file ./variables.json`
`variables export`	Exporta variáveis para um ficheiro local.	`apidog variables export --project <projectId> --scope global --output ./variables.json`

Recursos de Design de API

Utilize estes comandos para gerir recursos de design de API, incluindo endpoints de API HTTP, esquemas, pastas, regras de mock, parâmetros comuns, componentes de resposta e esquemas de segurança. Ao criar ou atualizar recursos complexos, recomenda-se que execute primeiro cli-schema get <schemaKey> e cli-schema validate <schemaKey> --file <path>.

Endpoints de API HTTP

Comando	Descrição	Exemplo
`endpoint list`	Lista endpoints de API HTTP num projeto.	`apidog endpoint list --project <projectId>`
`endpoint get`	Consulta os detalhes do endpoint.	`apidog endpoint get <endpointId> --project <projectId>`
`endpoint create`	Cria um endpoint a partir de um ficheiro JSON.	`apidog endpoint create --project <projectId> --file ./endpoint.json`
`endpoint update`	Atualiza um endpoint.	`apidog endpoint update <endpointId> --project <projectId> --file ./endpoint.json`
`endpoint delete`	Elimina um endpoint.	`apidog endpoint delete <endpointId> --project <projectId>`
`cli-schema get endpoint-create`	Consulta o esquema para criação de endpoints.	`apidog cli-schema get endpoint-create`
`cli-schema get endpoint-update`	Consulta o esquema para atualizações de endpoints.	`apidog cli-schema get endpoint-update`

Esquemas de Dados

Comando	Descrição	Exemplo
`schema list`	Lista esquemas de dados num projeto.	`apidog schema list --project <projectId>`
`schema get`	Consulta os detalhes do esquema.	`apidog schema get <schemaId> --project <projectId>`
`schema create`	Cria um esquema de dados a partir de um ficheiro JSON.	`apidog schema create --project <projectId> --file ./schema.json`
`schema update`	Atualiza um esquema de dados.	`apidog schema update <schemaId> --project <projectId> --file ./schema.json`
`schema delete`	Elimina um esquema de dados.	`apidog schema delete <schemaId> --project <projectId>`
`cli-schema get schema-create`	Consulta o esquema para criação de esquemas de dados.	`apidog cli-schema get schema-create`
`cli-schema get schema-update`	Consulta o esquema para atualizações de esquemas de dados.	`apidog cli-schema get schema-update`

Documentos Markdown

Comando	Descrição	Exemplo
`doc list`	Lista documentos Markdown.	`apidog doc list --project <projectId>`
`doc get`	Consulta detalhes do documento Markdown.	`apidog doc get <docId> --project <projectId>`
`doc create`	Cria um documento Markdown.	`apidog doc create --project <projectId> --file ./doc.json`
`doc update`	Atualiza um documento Markdown.	`apidog doc update <docId> --project <projectId> --file ./doc.json`
`doc delete`	Elimina um documento Markdown.	`apidog doc delete <docId> --project <projectId>`

Pastas de Recursos

Utilize comandos folder para gerir árvores de pastas para diferentes tipos de recursos. A opção --type seleciona o tipo de recurso, como endpoint, schema, test-scenario, response-component, security-scheme, test-suite ou test-data.

Comando	Descrição	Exemplo
`folder list`	Lista pastas por tipo de recurso.	`apidog folder list --project <projectId> --type endpoint`
`folder create`	Cria uma pasta por tipo de recurso.	`apidog folder create --project <projectId> --type endpoint --name "New Folder"`
`folder move`	Move uma pasta para outra pasta principal.	`apidog folder move <folderId> --project <projectId> --type endpoint --parent <parentId>`
`folder update`	Atualiza o nome, a descrição ou a pasta principal.	`apidog folder update <folderId> --project <projectId> --type endpoint --name "New Folder Name"`
`folder delete`	Elimina uma pasta.	`apidog folder delete <folderId> --project <projectId> --type endpoint`
`cli-schema get folder-create`	Consulta o esquema para criação de pastas.	`apidog cli-schema get folder-create`
`cli-schema get folder-update`	Consulta o esquema para atualizações de pastas.	`apidog cli-schema get folder-update`

--type seleciona o tipo de pasta de recursos. Não é o nome da pasta. O campo description é suportado apenas para pastas endpoint e test-scenario; outros tipos de pastas suportam apenas atualizações de nome e pasta principal.

Regras de Mock

Comando	Descrição	Exemplo
`mock list`	Lista regras de mock num projeto ou sob um endpoint.	`apidog mock list --project <projectId> --http-api-id <endpointId>`
`mock get`	Consulta uma regra de mock.	`apidog mock get <mockId> --project <projectId>`
`mock create`	Cria uma regra de mock a partir de um ficheiro JSON.	`apidog mock create --project <projectId> --file ./mock.json`
`mock update`	Atualiza uma regra de mock.	`apidog mock update <mockId> --project <projectId> --file ./mock.json`
`mock delete`	Elimina uma regra de mock.	`apidog mock delete <mockId> --project <projectId>`
`cli-schema get mock-create`	Consulta o esquema para criação de regras de mock.	`apidog cli-schema get mock-create`
`cli-schema get mock-update`	Consulta o esquema para atualizações de regras de mock.	`apidog cli-schema get mock-update`

Parâmetros Comuns

Comando	Descrição	Exemplo
`common-parameter list`	Lista parâmetros comuns reutilizáveis.	`apidog common-parameter list --project <projectId>`
`common-parameter get`	Consulta detalhes de parâmetros comuns.	`apidog common-parameter get <commonParameterId> --project <projectId>`
`common-parameter create`	Cria um parâmetro comum a partir de um ficheiro JSON.	`apidog common-parameter create --project <projectId> --file ./common-parameter.json`
`common-parameter update`	Atualiza um parâmetro comum.	`apidog common-parameter update <commonParameterId> --project <projectId> --file ./common-parameter.json`
`common-parameter import`	Importa parâmetros comuns a partir de um ficheiro.	`apidog common-parameter import --project <projectId> --file ./common-parameters.json`
`common-parameter export`	Exporta parâmetros comuns para um ficheiro local.	`apidog common-parameter export --project <projectId> --output ./common-parameters.json`

Componentes de Resposta

Comando	Descrição	Exemplo
`response-component list`	Lista componentes de resposta reutilizáveis.	`apidog response-component list --project <projectId>`
`response-component get`	Consulta detalhes de componentes de resposta.	`apidog response-component get <responseComponentId> --project <projectId>`
`response-component create`	Cria um componente de resposta a partir de um ficheiro JSON.	`apidog response-component create --project <projectId> --file ./response-component.json`
`response-component update`	Atualiza um componente de resposta.	`apidog response-component update <responseComponentId> --project <projectId> --file ./response-component.json`
`response-component delete`	Elimina um componente de resposta.	`apidog response-component delete <responseComponentId> --project <projectId>`

Esquemas de Segurança

Comando	Descrição	Exemplo
`security-scheme list`	Lista esquemas de segurança num projeto.	`apidog security-scheme list --project <projectId>`
`security-scheme get`	Consulta detalhes do esquema de segurança.	`apidog security-scheme get <schemeId> --project <projectId>`
`security-scheme create`	Cria um esquema de segurança a partir de um ficheiro JSON.	`apidog security-scheme create --project <projectId> --file ./scheme.json`
`security-scheme update`	Atualiza um esquema de segurança.	`apidog security-scheme update <schemeId> --project <projectId> --file ./scheme.json`
`security-scheme delete`	Elimina um esquema de segurança.	`apidog security-scheme delete <schemeId> --project <projectId>`

Os caminhos de API são caminhos de recursos de API, não caminhos de ficheiros locais. Se a sua shell reescrever valores que começam por /, coloque o caminho entre aspas, por exemplo --path '/api/users', ou utilize --file para fornecer dados do endpoint.

Para casos de teste de API ou passos HTTP de cenários de teste, responseId deve utilizar um ID de definição de resposta de endpoint de endpoint.responses[].id, não um ID de componente de resposta. Para reutilizar um componente de resposta, associe-o primeiro na definição de resposta do endpoint.

Testes Automatizados

Utilize estes comandos para gerir casos de teste de API, cenários de teste, conjuntos de testes, dados de teste, relatórios de teste, runners e tarefas agendadas.

Casos de Teste de API

Comando	Descrição	Exemplo
`test-case list`	Lista casos de teste de API, opcionalmente filtrados por endpoint.	`apidog test-case list --project <projectId> --endpoint <endpointId>`
`test-case category`	Lista categorias de casos de teste.	`apidog test-case category --project <projectId>`
`test-case get`	Consulta detalhes de casos de teste de API.	`apidog test-case get <caseId> --project <projectId>`
`test-case create`	Cria um caso de teste de API a partir de um ficheiro JSON.	`apidog test-case create --project <projectId> --file ./case.json`
`test-case update`	Atualiza um caso de teste de API.	`apidog test-case update <caseId> --project <projectId> --file ./case.json`
`test-case delete`	Elimina um caso de teste de API.	`apidog test-case delete <caseId> --project <projectId>`
`cli-schema get test-case-create`	Consulta o esquema para criação de casos de teste.	`apidog cli-schema get test-case-create`
`cli-schema get test-case-update`	Consulta o esquema para atualizações de casos de teste.	`apidog cli-schema get test-case-update`

Cenários de Teste

Comando	Descrição	Exemplo
`test-scenario list`	Lista cenários de teste num projeto.	`apidog test-scenario list --project <projectId>`
`test-scenario get`	Consulta detalhes do cenário de teste.	`apidog test-scenario get <scenarioId> --project <projectId>`
`test-scenario create`	Cria um cenário de teste.	`apidog test-scenario create --project <projectId> --file ./scenario.json`
`test-scenario update`	Atualiza um cenário de teste.	`apidog test-scenario update <scenarioId> --project <projectId> --file ./scenario.json`
`test-scenario delete`	Elimina um cenário de teste.	`apidog test-scenario delete <scenarioId> --project <projectId>`
`test-scenario run`	Executa um cenário de teste.	`apidog test-scenario run <scenarioId> --project <projectId> --environment <environmentId>`
`cli-schema get test-scenario-create`	Consulta o esquema para criação de cenários de teste.	`apidog cli-schema get test-scenario-create`
`cli-schema get test-scenario-update`	Consulta o esquema para atualizações de cenários de teste.	`apidog cli-schema get test-scenario-update`

Conjuntos de Testes

Comando	Descrição	Exemplo
`test-suite list`	Lista conjuntos de testes num projeto.	`apidog test-suite list --project <projectId>`
`test-suite get`	Consulta detalhes do conjunto de testes.	`apidog test-suite get <testSuiteId> --project <projectId>`
`test-suite create`	Cria um conjunto de testes.	`apidog test-suite create --project <projectId> --file ./suite.json`
`test-suite update`	Atualiza um conjunto de testes.	`apidog test-suite update <testSuiteId> --project <projectId> --file ./suite.json`
`test-suite delete`	Elimina um conjunto de testes.	`apidog test-suite delete <testSuiteId> --project <projectId>`
`test-suite run`	Executa um conjunto de testes.	`apidog test-suite run <testSuiteId> --project <projectId> --environment <environmentId>`

Dados de Teste

Comando	Descrição	Exemplo
`test-data list`	Lista conjuntos de dados de teste.	`apidog test-data list --project <projectId>`
`test-data get`	Consulta detalhes do conjunto de dados de teste.	`apidog test-data get <dataId> --project <projectId>`
`test-data create`	Cria um conjunto de dados de teste a partir de um ficheiro JSON.	`apidog test-data create --project <projectId> --file ./test-data.json`
`test-data update`	Atualiza um conjunto de dados de teste.	`apidog test-data update <dataId> --project <projectId> --file ./test-data.json`
`test-data delete`	Elimina um conjunto de dados de teste.	`apidog test-data delete <dataId> --project <projectId>`

Relatórios de Teste

Comando	Descrição	Exemplo
`test-report list`	Lista relatórios de teste num projeto.	`apidog test-report list --project <projectId>`
`test-report get`	Consulta detalhes do relatório de teste.	`apidog test-report get <reportId> --project <projectId>`
`test-report download`	Transfere um relatório de teste para um ficheiro local.	`apidog test-report download <reportId> --project <projectId> --format json --output ./report.json`
`test-report delete`	Elimina um relatório de teste.	`apidog test-report delete <reportId> --project <projectId>`

Runners

Comando	Descrição	Exemplo
`runner list`	Lista runners num projeto ou equipa.	`apidog runner list --project <projectId>`
`runner get`	Consulta detalhes do runner.	`apidog runner get <runnerId> --project <projectId>`
`runner create`	Cria um runner de equipa.	`apidog runner create --team <teamId> --name <name> --runner-type <runnerType> --server-type <serverType>`
`runner check`	Verifica o estado do runner.	`apidog runner check <runnerId> --team <teamId>`
`runner delete`	Elimina um runner.	`apidog runner delete <runnerId> --project <projectId>`

Tarefas Agendadas

Comando	Descrição	Exemplo
`scheduled-task list`	Lista tarefas agendadas num projeto.	`apidog scheduled-task list --project <projectId>`
`scheduled-task get`	Consulta detalhes da tarefa agendada.	`apidog scheduled-task get <taskId> --project <projectId>`
`scheduled-task create`	Cria uma tarefa agendada a partir de um ficheiro JSON.	`apidog scheduled-task create --project <projectId> --file ./scheduled-task.json`
`scheduled-task update`	Atualiza uma tarefa agendada.	`apidog scheduled-task update <taskId> --project <projectId> --file ./scheduled-task.json`
`scheduled-task delete`	Elimina uma tarefa agendada.	`apidog scheduled-task delete <taskId> --project <projectId>`
`scheduled-task run`	Aciona manualmente uma tarefa agendada.	`apidog scheduled-task run <taskId> --project <projectId>`

Comando de Execução Principal: `apidog run`

Este é o comando principal para executar cenários de teste, pastas de cenários de teste, conjuntos de testes ou ficheiros exportados locais. Pode copiar comandos gerados a partir do painel de CI/CD do cliente Apidog e executá-los no seu terminal ou fluxo de trabalho de CI/CD.

Execução Online

Ao executar testes em tempo real através do servidor Apidog, utilize o seguinte comando.

Utilize o token de acesso do Apidog juntamente com o ID de um cenário de teste específico, diretório de cenários de teste ou conjunto de testes. Por exemplo:

Execução Local

Ao executar testes offline utilizando ficheiros exportados, utilize o seguinte comando.

Especifique o URL ou o caminho do ficheiro do cenário de teste do Apidog. Por exemplo:

Opções de Execução

Opção	Descrição
`--access-token <accessToken>`	Define o token de autenticação para execução online
`-t, --test-scenario <testScenarioId>`	Especifica o ID do cenário de teste a executar
`-f, --test-scenario-folder <folderId>`	Especifica o ID do diretório de cenários de teste a executar
`--test-suite <testSuiteId>`	Especifica o ID do conjunto de testes a executar
`--project <projectId>`	Especifica o ID do projeto
`--branch <branchName>`	Especifica o nome da branch; se omitido, o servidor utiliza por predefinição a branch principal
`-r, --reporters [reporters]`	Especifica tipos de relatórios de teste (predefinição: `["cli"]`)
`--out-dir <outDir>`	Diretório de saída para relatórios de teste (predefinição: `./apidog-reports`)
`--out-file <outFile>`	Nome do ficheiro de relatório de teste sem necessidade de adicionar uma extensão de ficheiro. Pode utilizar `{FOLDER_NAME}`, `{SCENARIO_NAME}` e `{GENERATE_TIME}`
`--out-json-failures-separated <outJsonFailuresSeparated>`	Exporta falhas como ficheiro JSON separado
`-e, --environment <environmentId>`	Especifica o ambiente de execução
`-n, --iteration-count <n>`	Define o número de iterações
`-d, --iteration-data <path>`	Define dados para iterações de casos (JSON ou CSV)
`--on-error <behavior>`	Define o comportamento de tratamento de erros (`ignore`, `continue` ou `end`)
`--variables <path>`	Carrega variáveis de ambiente ou globais a partir de um ficheiro local
`--global-var <value>`	Define variáveis globais (formato `key=value`)
`--env-var <value>`	Define variáveis de ambiente (formato `key=value`)
`--notification <ids>`	Envia notificações após a conclusão da execução
`--notification-failed-event <ids>`	Envia notificações apenas quando a execução falha
`--external-program-path <path>`	Especifica o caminho do ficheiro para programas externos
`--database-connection <path>`	Especifica o caminho do ficheiro para a configuração da base de dados
`--ignore-redirects`	Impede redirecionamentos automáticos
`--silent`	Impede a saída na consola
`--color <value>`	Ativa ou desativa a saída colorida na consola
`--delay-request [n]`	Especifica o atraso entre pedidos (ms)
`--timeout-request [n]`	Especifica o tempo limite do pedido (ms)
`--timeout-script [n]`	Especifica o tempo limite de execução do script (ms)
`-k, --insecure`	Desativa a verificação SSL
`--ssl-client-cert-list <path>`	Especifica o caminho da configuração de certificados de cliente
`--ssl-client-cert <path>`	Especifica o caminho do certificado de cliente (PEM)
`--ssl-client-key <path>`	Especifica o caminho da chave privada do certificado de cliente
`--ssl-client-passphrase <passphrase>`	Especifica a frase-passe do certificado de cliente
`--ssl-extra-ca-certs <path>`	Especifica certificados CA de confiança adicionais
`-b, --bigint`	Ativa compatibilidade com bigint
`--upload-report [value]`	Carrega a visão geral do relatório de teste para a cloud
`--preferred-http-version <preferredHttpVersion>`	Define a versão preferida do protocolo HTTP
`--verbose`	Apresenta informações detalhadas do pedido e da resposta
`--lang <language>`	Define o idioma da CLI (en)
`-h, --help`	Apresenta informações de ajuda

Ao criar ou atualizar recursos de teste complexos, como cenários de teste, conjuntos de testes, casos de teste, dados de teste ou tarefas agendadas, utilize primeiro cli-schema get <schemaKey> e, em seguida, valide o seu ficheiro local com cli-schema validate <schemaKey> --file <path>.

Importação e Exportação

Utilize comandos de importação e exportação para trazer documentos de API externos para o Apidog ou exportar dados de projeto para formatos utilizados por outras ferramentas.

Importar Dados do Projeto

O comando import importa um ficheiro local para um projeto. Os formatos suportados incluem openapi, postman, har, insomnia, jmeter, wsdl, yapi, rap2, apidoc, hoppscotch, markdown, jsonschema e apidog.

Comando	Descrição	Exemplo
`import`	Importa um ficheiro local para um projeto por formato.	`apidog import --project <projectId> --format openapi --file ./openapi.json`

Definições de Importação Automática

Utilize import auto-import para manter definições de importação automática para sincronização de longo prazo a partir de fontes externas.

Comando	Descrição	Exemplo
`import auto-import list`	Lista definições de importação automática num projeto.	`apidog import auto-import list --project <projectId>`
`import auto-import create`	Cria uma definição de importação automática.	`apidog import auto-import create --project <projectId> --file ./auto-import.json`
`import auto-import get`	Consulta uma definição de importação automática.	`apidog import auto-import get <settingId> --project <projectId>`
`import auto-import delete`	Elimina uma definição de importação automática.	`apidog import auto-import delete <settingId> --project <projectId>`
`cli-schema get import-auto-import-create`	Consulta o esquema para definições de importação automática.	`apidog cli-schema get import-auto-import-create`

Exportar Dados do Projeto

O comando export exporta dados do projeto para um ficheiro local. Os formatos suportados incluem openapi, markdown, html, postman e apidog.

Para exportação nativa apidog, o âmbito suporta all, apis e tags. O âmbito de pasta está disponível apenas para exportação OpenAPI.

Comando	Descrição	Exemplo
`export`	Exporta dados do projeto por formato.	`apidog export --project <projectId> --format openapi --output ./openapi.json`
`export --format apidog`	Exporta dados nativos do projeto.	`apidog export --project <projectId> --format apidog --output ./project.apidog.json`
`export --scope apis`	Exporta APIs selecionadas em formato nativo.	`apidog export --project <projectId> --format apidog --scope apis --api-ids 1001,1002 --output ./selected.apidog.json`
`export --scope tags`	Exporta APIs por etiquetas em formato nativo.	`apidog export --project <projectId> --format apidog --scope tags --include-tags pet,store --output ./tagged.apidog.json`
`export --format openapi --scope folders`	Exporta pastas selecionadas em formato OpenAPI.	`apidog export --project <projectId> --format openapi --scope folders --folder-ids 2001 --output ./openapi.json`

Definições de Exportação OAS

Utilize export settings para manter definições de exportação OAS reutilizáveis.

Comando	Descrição	Exemplo
`export settings list`	Lista definições de exportação OAS.	`apidog export settings list --project <projectId>`
`export settings create`	Cria uma definição de exportação OAS.	`apidog export settings create --project <projectId> --file ./export-setting.json`
`export settings get`	Consulta uma definição de exportação OAS.	`apidog export settings get <settingId> --project <projectId>`
`export settings update`	Atualiza uma definição de exportação OAS.	`apidog export settings update <settingId> --project <projectId> --file ./export-setting.json`
`export settings delete`	Elimina uma definição de exportação OAS.	`apidog export settings delete <settingId> --project <projectId>`
`cli-schema get export-settings-create`	Consulta o esquema para criação de definições de exportação OAS.	`apidog cli-schema get export-settings-create`
`cli-schema get export-settings-update`	Consulta o esquema para atualizações de definições de exportação OAS.	`apidog cli-schema get export-settings-update`

Partilha de Documentação

Utilize estes comandos para publicar e partilhar documentação de API.

Sites de Documentação

Comando	Descrição	Exemplo
`docs-site list`	Lista sites de documentação.	`apidog docs-site list --project <projectId>`
`docs-site get`	Consulta detalhes do site de documentação.	`apidog docs-site get <siteId> --project <projectId>`
`docs-site create`	Cria um site de documentação.	`apidog docs-site create --project <projectId> --file ./docs-site.json`
`docs-site update`	Atualiza definições do site de documentação.	`apidog docs-site update <siteId> --project <projectId> --file ./docs-site.json`
`docs-site delete`	Elimina um site de documentação.	`apidog docs-site delete <siteId> --project <projectId>`

Documentos Partilhados

Comando	Descrição	Exemplo
`shared-doc list`	Lista documentos partilhados.	`apidog shared-doc list --project <projectId>`
`shared-doc get`	Consulta detalhes do documento partilhado.	`apidog shared-doc get <docId> --project <projectId>`
`shared-doc create`	Cria um documento partilhado.	`apidog shared-doc create --project <projectId> --file ./shared-doc.json`
`shared-doc update`	Atualiza definições do documento partilhado.	`apidog shared-doc update <docId> --project <projectId> --file ./shared-doc.json`
`shared-doc delete`	Elimina um documento partilhado.	`apidog shared-doc delete <docId> --project <projectId>`

Gestão de Branches

Utilize comandos de branch para isolar alterações, colaborar em recursos do projeto e intercalar recursos selecionados entre branches.

Branches de Iteração

Comando	Descrição	Exemplo
`branch list --type all`	Lista todos os tipos de branches num projeto.	`apidog branch list --project <projectId> --type all`
`branch list --type sprint`	Lista branches de iteração.	`apidog branch list --project <projectId> --type sprint`
`branch get --type sprint`	Consulta uma branch de iteração.	`apidog branch get <branchName> --project <projectId> --type sprint`
`branch create --type sprint`	Cria uma branch de iteração.	`apidog branch create --project <projectId> --type sprint --name <branchName> --from main`
`branch update --type sprint`	Atualiza uma branch de iteração.	`apidog branch update <branchName> --project <projectId> --type sprint --name <newName>`
`branch merge`	Intercala recursos explicitamente selecionados de uma branch para outra.	`apidog branch merge --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`branch pick-to`	Seleciona recursos de uma branch de origem para uma branch de destino.	`apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`branch archive --type sprint`	Arquiva uma branch de iteração antes da eliminação.	`apidog branch archive <branchName> --project <projectId> --type sprint`
`branch delete --type sprint`	Elimina uma branch de iteração arquivada.	`apidog branch delete <branchName> --project <projectId> --type sprint`

Branches de IA

Comando	Descrição	Exemplo
`branch list --type ai`	Lista branches de IA.	`apidog branch list --project <projectId> --type ai`
`branch get --type ai`	Consulta uma branch de IA.	`apidog branch get <branchName> --project <projectId> --type ai`
`branch create --type ai`	Cria uma branch de IA a partir de uma branch de origem.	`apidog branch create --project <projectId> --type ai --name <aiBranchName> --from <sourceBranchName>`
`branch update --type ai`	Atualiza uma branch de IA.	`apidog branch update <branchName> --project <projectId> --type ai --name <newName>`
`branch archive --type ai`	Arquiva uma branch de IA antes da eliminação.	`apidog branch archive <branchName> --project <projectId> --type ai`
`branch delete --type ai`	Elimina uma branch de IA arquivada.	`apidog branch delete <branchName> --project <projectId> --type ai`

Branches Gerais

Comando	Descrição	Exemplo
`branch list --type general`	Lista branches gerais.	`apidog branch list --project <projectId> --type general`
`branch get --type general`	Consulta uma branch geral.	`apidog branch get <branchName> --project <projectId> --type general`
`branch create --type general`	Cria uma branch geral.	`apidog branch create --project <projectId> --type general --name <branchName> --from main`
`branch update --type general`	Atualiza uma branch geral.	`apidog branch update <branchName> --project <projectId> --type general --name <newName>`
`branch delete --type general`	Elimina uma branch geral.	`apidog branch delete <branchName> --project <projectId> --type general`

Os comandos de criação de branches utilizam principalmente opções de linha de comando, como --type, --name e --from. cli-schema get branch-*-create é utilizado para inspecionar a estrutura das opções de criação. Para as opções reais do comando, execute apidog branch create -h.

Pedidos de Merge

Utilize merge-request quando a branch de destino exigir um fluxo de revisão. Os pedidos de merge e merges diretos apenas intercalam recursos explicitamente selecionados.

Comando	Descrição	Exemplo
`merge-request preview`	Analisa alterações candidatas antes de criar um pedido de merge ou merge direto.	`apidog merge-request preview --project <projectId> --from <sourceBranchName> --to <targetBranchName>`
`merge-request list`	Lista pedidos de merge.	`apidog merge-request list --project <projectId> --to <targetBranchName>`
`merge-request get`	Consulta detalhes do pedido de merge.	`apidog merge-request get <mergeRequestId> --project <projectId> --to <targetBranchName>`
`merge-request create`	Cria um pedido de merge.	`apidog merge-request create --project <projectId> --to <targetBranchName> --from <sourceBranchName> --reviewer-ids <userIds> --endpoint-ids <ids>`
`merge-request update`	Atualiza um pedido de merge.	`apidog merge-request update <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./merge-request.json`
`merge-request approve`	Aprova um pedido de merge.	`apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json`
`merge-request reject`	Rejeita um pedido de merge.	`apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName>`
`merge-request delete`	Elimina um pedido de merge.	`apidog merge-request delete <mergeRequestId> --project <projectId> --to <targetBranchName>`

Para manter os recursos do projeto seguros, as permissões de escrita da CLI podem estar restringidas por predefinição. Pode editar dados da branch de origem através de uma branch de IA ou ativar permissões de edição externa nas definições de funcionalidades do projeto quando for necessária edição direta para a branch principal, branches de iteração padrão ou branches gerais. As alterações efetuadas numa branch de IA continuam a necessitar de confirmação do utilizador antes de merge ou merge-request.

Recomenda-se que os nomes de branches de IA incluam a data, a branch de origem e a finalidade, por exemplo ai/20260312-from-main-user-register.

Para operações de merge e seleção de branches, as opções de ID de recursos utilizam nomes no plural e IDs numéricos separados por vírgulas, como --endpoint-ids 1,2, --doc-ids 3,4 e --test-suite-ids 5,6.

Outros Recursos

Utilize estes comandos para gerir recursos de extensão de projetos e ligações externas.

Campos Personalizados

Comando	Descrição	Exemplo
`custom-field list`	Lista campos personalizados.	`apidog custom-field list --project <projectId>`
`custom-field create`	Cria um campo personalizado.	`apidog custom-field create --project <projectId> --file ./custom-field.json`
`custom-field update`	Atualiza um campo personalizado.	`apidog custom-field update <customFieldId> --project <projectId> --file ./custom-field.json`
`custom-field delete`	Elimina um campo personalizado.	`apidog custom-field delete <customFieldId> --project <projectId>`

APIs WebSocket

Comando	Descrição	Exemplo
`websocket list`	Lista APIs WebSocket.	`apidog websocket list --project <projectId>`
`websocket get`	Consulta detalhes da API WebSocket.	`apidog websocket get <websocketId> --project <projectId>`
`websocket create`	Cria uma API WebSocket.	`apidog websocket create --project <projectId> --name <name> --url <url>`
`websocket update`	Atualiza uma API WebSocket.	`apidog websocket update <websocketId> --project <projectId> --file ./websocket.json`
`websocket delete`	Elimina uma API WebSocket.	`apidog websocket delete <websocketId> --project <projectId>`

APIs Socket.IO

Comando	Descrição	Exemplo
`socketio list`	Lista APIs Socket.IO.	`apidog socketio list --project <projectId>`
`socketio get`	Consulta detalhes da API Socket.IO.	`apidog socketio get <socketioId> --project <projectId>`
`socketio create`	Cria uma API Socket.IO.	`apidog socketio create --project <projectId> --file ./socketio.json`
`socketio update`	Atualiza uma API Socket.IO.	`apidog socketio update <socketioId> --project <projectId> --file ./socketio.json`
`socketio delete`	Elimina uma API Socket.IO.	`apidog socketio delete <socketioId> --project <projectId>`

Scripts Comuns

Comando	Descrição	Exemplo
`common-script list`	Lista scripts comuns.	`apidog common-script list --project <projectId>`
`common-script get`	Consulta detalhes do script comum.	`apidog common-script get <scriptId> --project <projectId>`
`common-script create`	Cria um script comum.	`apidog common-script create --project <projectId> --file ./common-script.json`
`common-script update`	Atualiza um script comum.	`apidog common-script update <scriptId> --project <projectId> --file ./common-script.json`
`common-script delete`	Elimina um script comum.	`apidog common-script delete <scriptId> --project <projectId>`

Ligações de Base de Dados

Comando	Descrição	Exemplo
`database-connection list`	Lista ligações de base de dados.	`apidog database-connection list --project <projectId>`
`database-connection get`	Consulta detalhes da ligação de base de dados.	`apidog database-connection get <connectionId> --project <projectId>`
`database-connection create`	Cria uma ligação de base de dados.	`apidog database-connection create --project <projectId> --file ./database-connection.json`
`database-connection update`	Atualiza uma ligação de base de dados.	`apidog database-connection update <connectionId> --project <projectId> --file ./database-connection.json`
`database-connection delete`	Elimina uma ligação de base de dados.	`apidog database-connection delete <connectionId> --project <projectId>`

Fornecedores de Cofre

Comando	Descrição	Exemplo
`vault list`	Lista fornecedores de cofre.	`apidog vault list --project <projectId>`
`vault get`	Consulta detalhes do fornecedor de cofre.	`apidog vault get <vaultProviderId> --project <projectId>`
`vault create`	Cria um fornecedor de cofre.	`apidog vault create --project <projectId> --file ./vault.json`
`vault update`	Atualiza um fornecedor de cofre.	`apidog vault update <vaultProviderId> --project <projectId> --file ./vault.json`
`vault delete`	Elimina um fornecedor de cofre.	`apidog vault delete <vaultProviderId> --project <projectId>`

Ligações Git

Comando	Descrição	Exemplo
`git-connection list`	Lista ligações Git.	`apidog git-connection list --project <projectId>`
`git-connection get`	Consulta detalhes da ligação Git.	`apidog git-connection get <connectionId> --project <projectId>`
`git-connection create`	Cria uma ligação Git.	`apidog git-connection create --project <projectId> --file ./git-connection.json`
`git-connection update`	Atualiza uma ligação Git.	`apidog git-connection update <connectionId> --project <projectId> --file ./git-connection.json`
`git-connection delete`	Elimina uma ligação Git.	`apidog git-connection delete <connectionId> --project <projectId>`

Gestão e Definições

Utilize estes comandos para administração de projetos, notificações, recursos da reciclagem, histórico de alterações e registos de auditoria.

Notificações

Comando	Descrição	Exemplo
`notification list`	Lista configurações de notificações.	`apidog notification list --project <projectId>`
`notification get`	Consulta detalhes da notificação.	`apidog notification get <notificationId> --project <projectId>`
`notification create`	Cria uma configuração de notificação.	`apidog notification create --project <projectId> --file ./notification.json`
`notification update`	Atualiza uma configuração de notificação.	`apidog notification update <notificationId> --project <projectId> --file ./notification.json`
`notification delete`	Elimina uma configuração de notificação.	`apidog notification delete <notificationId> --project <projectId>`

Reciclagem

Comando	Descrição	Exemplo
`recycle list`	Lista recursos na reciclagem.	`apidog recycle list --project <projectId>`
`recycle restore`	Restaura um recurso da reciclagem.	`apidog recycle restore <itemId> --project <projectId>`
`recycle delete`	Elimina permanentemente um recurso da reciclagem.	`apidog recycle delete <itemId> --project <projectId>`

Histórico

Comando	Descrição	Exemplo
`history list`	Lista o histórico de alterações do projeto.	`apidog history list --project <projectId>`
`history get`	Consulta detalhes do histórico de alterações.	`apidog history get <historyId> --project <projectId>`

Registos de Auditoria

Comando	Descrição	Exemplo
`audit-log list`	Lista registos de auditoria do projeto.	`apidog audit-log list --project <projectId>`
`audit-log get`	Consulta detalhes do registo de auditoria.	`apidog audit-log get <auditLogId> --project <projectId>`

Utilização Avançada

Carregar Ficheiros na CLI

Ao trabalhar com APIs que exigem carregamentos de ficheiros, definir com precisão o caminho do ficheiro a carregar é crucial. Deve armazenar o ficheiro na mesma máquina onde os testes são executados e referenciá-lo utilizando o respetivo caminho absoluto ou relativo. Siga estes passos para referenciar um ficheiro a carregar.

Copie previamente o ficheiro necessário para a máquina que executa a CLI. Por exemplo, se estiver a utilizar GitHub Actions como pipeline de CI/CD, copie o ficheiro necessário para o mesmo repositório GitHub que o do seu fluxo de trabalho.

No Apidog, navegue para o seu cenário de teste e localize o passo que exige o carregamento de ficheiro. Clique no botão Bulk Edit, conforme apresentado abaixo.

Botão de edição em lote nos detalhes do passo do cenário de teste

Copie o caminho do ficheiro que copiou para a máquina da CLI. Em seguida, substitua o valor do parâmetro do campo de ficheiro pelo caminho do ficheiro na máquina da CLI. Por exemplo, se colocar um ficheiro png na pasta data num repositório GitHub, pode utilizar data/to-be-uploaded.png para o referenciar.

Configuração do caminho do ficheiro no modo de edição em lote

Após esta configuração, o ficheiro pode ser enviado corretamente para o Apidog através da CLI.

Se quiser executar novamente este cenário de teste localmente, terá de modificar o caminho do ficheiro no valor do parâmetro de volta para o caminho na sua máquina local.

Utilizar Operações de Base de Dados na CLI

Quando os seus cenários de teste incluem operações de base de dados, precisa de realizar alguns passos adicionais, porque as configurações da base de dados são guardadas localmente, não na cloud. Isto significa que não pode executar diretamente a CLI em modo cloud para estes cenários. Eis como lidar com esta situação:

Para cenários de teste que incluem operações de base de dados, verá uma indicação na interface de geração de linha de comando: "Download the database configuration file."

Transfira este ficheiro e coloque-o no diretório onde planeia executar a CLI do Apidog.

A linha de comando gerada automaticamente incluirá a opção --database-connection. Pode utilizar esta linha de comando tal como está para executar os seus testes.

Carregar Relatórios de Teste Locais da CLI para a Cloud

Para carregar os seus relatórios de teste locais da CLI para a cloud, pode adicionar o parâmetro --upload-report no final do seu comando da CLI. Eis como fazê-lo:

Adicione o parâmetro --upload-report ao seu comando da CLI:

Este comando executará os seus testes e carregará automaticamente o relatório de teste para a cloud após a conclusão.

Para consultar o relatório carregado:

Aceda à secção "Test Reports" no seu painel do Apidog.

Procure a coluna "Team Reports".

Nota: Para relatórios carregados através da CLI, o campo "Tester" será apresentado como vazio.

Utilizar Scripts/Programas Externos na CLI

Pode referenciar scripts ou programas externos ao executar a CLI do Apidog adicionando o respetivo caminho no final do comando. Eis como fazê-lo:

Neste exemplo, a CLI é instruída a referenciar programas localizados no diretório ./scripts. Se não for especificada qualquer hierarquia, a predefinição é o diretório atual de execução da CLI.

Existem duas abordagens principais para gerir estes scripts externos:

1. Caminho Local

Para evitar confusão na gestão de scripts locais, recomenda-se:

Organizar todos os ficheiros de script por categoria

Colocá-los num diretório específico

Especificar o caminho local correspondente no comando da CLI

2. Repositório de Código na Cloud

Em alternativa, pode:

Alojar ficheiros de script num repositório de código baseado na cloud

Configurar comandos de pull no seu fluxo de trabalho de CI/CD para obter scripts externos para o ambiente local

Especificar o caminho real dos scripts externos no comando da CLI

SSL

Certificado de Cliente

A CLI do Apidog suporta a passagem de certificados de cliente.

Utilizar um Único Certificado de Cliente SSL

--ssl-client-cert
Especifique o caminho do certificado público de cliente SSL.

--ssl-client-key
Especifique o caminho do certificado privado de cliente SSL (opcional).

--ssl-client-passphrase
Especifique a frase-passe do cliente SSL (opcional).

Utilizar Ficheiro de Configuração de Certificados de Cliente SSL (Suporta Vários Certificados)

--ssl-client-cert-list
Especifique o caminho do ficheiro JSON da lista de certificados de cliente SSL. Por exemplo: ssl-client-cert-list.json

[
    {
        "name": "domain1",
        "matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
        "key": {"src": "/CI/client.domain1.key"},
        "cert": {"src": "/CI/client.domain1.crt"},
        "passphrase": "changeme"
    },
    {
        "name": "domain2",
        "matches": ["https://domain2.com/*"],
        "key": {"src": "/CI/client.domain2.key"},
        "cert": {"src": "/CI/client.domain2.crt"},
        "passphrase": "changeme"
    }
]

Esta opção suporta a definição de diferentes certificados de cliente SSL com base no URL ou nome de anfitrião. Tem precedência sobre as opções --ssl-client-cert, --ssl-client-key e --ssl-client-passphrase. Estas opções serão utilizadas como opções de recurso se não houver correspondência para o URL na lista.

HTTP/2

A CLI pode ser configurada para utilizar versões específicas de protocolo para enviar pedidos através do parâmetro --preferred-http-version.

Valores do parâmetro de versão do protocolo:

"HTTP/2" - HTTP/2 Application-Layer Protocol Negotiation (ALPN), suportado apenas para pedidos HTTPS.

"HTTP/2-with-prior-knowledge" - HTTP/2 com conhecimento prévio.

"HTTP/1" - HTTP/1.1.

O parâmetro suporta as seguintes configurações:

Definir diferentes versões de protocolo para pedidos HTTPS e HTTP:

Definir a mesma versão de protocolo para HTTPS e HTTP:

Definir HTTP/2 para HTTPS e HTTP (valores não suportados serão automaticamente ignorados):

FAQ

Como lidar com a mensagem de erro Invalid character in header content['Authorization']?

Este erro é normalmente causado por caracteres inválidos no cabeçalho Authorization, como caracteres não ASCII, quebras de linha ou espaços adicionais. Se tiver a certeza de que a execução de cenários de teste no cliente Apidog ou na interface Web não produz quaisquer erros, verifique se definiu valores INITIAL para variáveis no seu ambiente e confirme que o valor Authorization corresponde ao formato esperado.

Como posso editar dados do projeto diretamente sem utilizar uma branch de IA?

As permissões de escrita do projeto podem estar restringidas por motivos de segurança. Verifique as definições de funcionalidades do projeto e ative permissões de edição externa quando for necessária edição direta.

Opções da CLI do Apidog

Sintaxe Básica da CLI do Apidog#

Autenticação#

Esquema da CLI#

Equipas e Projetos#

Gestão de Equipas#

Gestão de Projetos#

Definições do Projeto#

Ambientes e Variáveis#

Gestão de Ambientes#

Gestão de Variáveis#

Recursos de Design de API#

Endpoints de API HTTP#

Esquemas de Dados#

Documentos Markdown#

Pastas de Recursos#

Regras de Mock#

Parâmetros Comuns#

Componentes de Resposta#

Esquemas de Segurança#

Testes Automatizados#

Casos de Teste de API#

Cenários de Teste#

Conjuntos de Testes#

Dados de Teste#

Relatórios de Teste#

Runners#

Tarefas Agendadas#

Comando de Execução Principal: apidog run#

Execução Online#

Execução Local#

Opções de Execução#

Importação e Exportação#

Importar Dados do Projeto#

Definições de Importação Automática#

Exportar Dados do Projeto#

Definições de Exportação OAS#

Partilha de Documentação#

Sites de Documentação#

Documentos Partilhados#

Gestão de Branches#

Branches de Iteração#

Branches de IA#

Branches Gerais#

Pedidos de Merge#

Outros Recursos#

Campos Personalizados#

APIs WebSocket#

APIs Socket.IO#

Scripts Comuns#

Ligações de Base de Dados#

Fornecedores de Cofre#

Ligações Git#

Gestão e Definições#

Notificações#

Reciclagem#

Histórico#

Registos de Auditoria#

Utilização Avançada#

Carregar Ficheiros na CLI#

Utilizar Operações de Base de Dados na CLI#

Carregar Relatórios de Teste Locais da CLI para a Cloud#

Utilizar Scripts/Programas Externos na CLI#

1. Caminho Local#

2. Repositório de Código na Cloud#

SSL#

Certificado de Cliente#

Utilizar um Único Certificado de Cliente SSL#

Utilizar Ficheiro de Configuração de Certificados de Cliente SSL (Suporta Vários Certificados)#

HTTP/2#

FAQ#

Sintaxe Básica da CLI do Apidog

Autenticação

Esquema da CLI

Equipas e Projetos

Gestão de Equipas

Gestão de Projetos

Definições do Projeto

Ambientes e Variáveis

Gestão de Ambientes

Gestão de Variáveis

Recursos de Design de API

Endpoints de API HTTP

Esquemas de Dados

Documentos Markdown

Pastas de Recursos

Regras de Mock

Parâmetros Comuns

Componentes de Resposta

Esquemas de Segurança

Testes Automatizados

Casos de Teste de API

Cenários de Teste

Conjuntos de Testes

Dados de Teste

Relatórios de Teste

Runners

Tarefas Agendadas

Comando de Execução Principal: `apidog run`

Execução Online

Execução Local

Opções de Execução

Importação e Exportação

Importar Dados do Projeto

Definições de Importação Automática

Exportar Dados do Projeto

Definições de Exportação OAS

Partilha de Documentação

Sites de Documentação

Documentos Partilhados

Gestão de Branches

Branches de Iteração

Branches de IA

Branches Gerais

Pedidos de Merge

Outros Recursos

Campos Personalizados

APIs WebSocket

APIs Socket.IO

Scripts Comuns

Ligações de Base de Dados

Fornecedores de Cofre

Ligações Git

Gestão e Definições

Notificações

Reciclagem

Histórico

Registos de Auditoria

Utilização Avançada

Carregar Ficheiros na CLI

Utilizar Operações de Base de Dados na CLI

Carregar Relatórios de Teste Locais da CLI para a Cloud

Utilizar Scripts/Programas Externos na CLI

1. Caminho Local

2. Repositório de Código na Cloud

SSL

Certificado de Cliente

Utilizar um Único Certificado de Cliente SSL

Utilizar Ficheiro de Configuração de Certificados de Cliente SSL (Suporta Vários Certificados)

HTTP/2

FAQ