DEV Community

Cover image for Como Permitir que um Agente de IA Atualize sua API Spec com o Apidog CLI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Permitir que um Agente de IA Atualize sua API Spec com o Apidog CLI

Editar uma especificação de API manualmente é meticuloso: renomear um campo, alterar um enum ou tornar um parâmetro obrigatório exige mudanças consistentes em todos os endpoints e esquemas que o referenciam. Esse é exatamente o tipo de tarefa que um agente de IA pode executar — desde que trabalhe com validação, isolamento e revisão humana.

Experimente o Apidog hoje

A CLI do Apidog fornece os controles necessários: valide o schema antes de gravar, execute mudanças em um branch isolado e envie o resultado para revisão via merge.

Este guia complementa o processo de permitir que um agente crie documentação de API. Criar documentação é uma tarefa aditiva; alterar um contrato existente exige mais salvaguardas para evitar mudanças incompatíveis.

O que significa atualizar uma especificação pela CLI

No Apidog, uma especificação contém endpoints e schemas de dados de um projeto. Há três caminhos principais para atualizá-la:

  • endpoint update: altera caminho, parâmetros, respostas ou configuração de um endpoint.
  • schema update: altera um modelo de dados referenciado por endpoints.
  • import: importa um arquivo OpenAPI para reconciliá-lo com o projeto.

Antes de automatizar qualquer um deles, entenda duas regras:

  1. update substitui estruturas completas; não aplica patch parcial.
  2. O agente deve trabalhar em um branch de IA, não diretamente no main.

Regra crítica: update substitui, não mescla

Os comandos update da CLI não funcionam como JSON Patch. Eles gravam os campos enviados e não mesclam itens de arrays por ID.

Por exemplo, enviar um array parameters com apenas um parâmetro alterado pode substituir o array inteiro e remover os demais parâmetros.

Use sempre o fluxo ler → modificar → validar → gravar:

# 1. Obtenha o recurso completo
apidog endpoint get <endpointId> --project <projectId>

# 2. Edite o objeto completo localmente.
# Mantenha todos os campos que não devem mudar.

# 3. Consulte e valide o schema do payload
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Atualize usando o objeto completo
apidog endpoint update <endpointId> \
  --project <projectId> \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

Inclua esta regra explicitamente no prompt ou nas instruções do agente:

Nunca envie um objeto parcial para update. Sempre busque o recurso completo, modifique apenas o necessário e envie o objeto inteiro de volta.

Essa prática evita perda silenciosa de campos e faz com que cli-schema validate detecte payloads inválidos antes da chamada de atualização.

Fluxo seguro: usar um branch de IA

Não conceda edição direta no branch principal para começar. Use um branch de IA para isolar as mudanças do agente até a revisão.

O fluxo é semelhante a abrir uma pull request para sua especificação:

  1. Crie um branch de IA.
  2. Importe para ele os recursos existentes que serão alterados.
  3. Execute o ciclo de leitura, modificação, validação e escrita no branch.
  4. Revise o diff e faça merge apenas após aprovação.

Passo 1: criar o branch de IA 

apidog branch create --project <projectId> --type ai \
  --from main \
  --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Uma convenção útil é:

ai/AAAA-MM-DD-da-origem-funcionalidade
Enter fullscreen mode Exit fullscreen mode

Exemplo:

ai/20260713-from-main-refund-fields
Enter fullscreen mode Exit fullscreen mode

Use --from com o branch principal ou um branch de sprint regular. Não use um branch geral.

Um branch de IA sem diferenças em relação à origem é arquivado automaticamente após 24 horas, o que ajuda a limpar experimentos abandonados.

Passo 2: trazer os recursos existentes para o branch

Um branch de IA começa vazio: ele não clona automaticamente os recursos do branch de origem.

Antes de editar um endpoint ou schema existente, use pick-to:

apidog branch pick-to --project <projectId> --type ai \
  --from main \
  --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

Você só precisa fazer isso para recursos já existentes que o agente vai modificar ou remover. Recursos novos podem ser criados diretamente no branch.

Se pular essa etapa, o agente encontrará um branch vazio e não terá o que editar.

Passo 3: executar a mudança no branch

Agora execute o mesmo ciclo de leitura-modificação-escrita, mas informe o branch de IA em todos os comandos:

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

O main permanece intocado. Se o agente cometer um erro, a mudança fica limitada a um branch descartável.

Passo 4: revisar e mesclar

As mudanças do branch de IA não voltam automaticamente para o branch de origem.

Quando o agente terminar, revise o diff. Se o destino estiver protegido, prefira uma solicitação de merge:

apidog merge-request --help
Enter fullscreen mode Exit fullscreen mode

Para merge direto:

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

O merge direto exige permissão de edição nos branches de origem e destino. Quando main estiver protegido, use merge-request e aprove a mudança no cliente Apidog.

Exemplo: renomear um campo com segurança

Suponha que o schema Refund tenha o campo amount e você queira migrá-lo para amountCents, usando inteiros em centavos.

A instrução para o agente pode ser:

Renomeie o campo amount no schema Refund para amountCents e altere seu tipo para inteiro.

Primeiro, busque o schema completo no branch de IA:

apidog schema get <refundSchemaId> \
  --project $PID \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

Em seguida, edite o objeto completo. Não envie somente a propriedade alterada:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Observe que orderId e reason continuam presentes. Como update substitui o conteúdo enviado, omitir esses campos poderia removê-los.

Valide e atualize:

# Valide o objeto completo
apidog cli-schema validate schema-create --file ./refund-full.json

# Atualize o schema no branch de IA
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

Depois, revise o diff: ele deve mostrar somente a renomeação de amount para amountCents e a alteração do tipo.

Bloqueie mudanças incompatíveis antes do merge

Renomear um campo obrigatório é uma mudança incompatível. Clientes que ainda enviam amount passarão a falhar na validação.

Faça o agente classificar cada alteração antes de solicitar merge:

Antes de mesclar qualquer alteração de especificação, classifique-a:

- Não disruptiva:
  novo campo opcional, novo endpoint ou restrição flexibilizada.
  → Resuma a alteração e prossiga para a solicitação de merge.

- Disruptiva:
  campo renomeado/removido, novo campo obrigatório ou tipo mais restrito.
  → PARE.
  Relate a alteração disruptiva, os endpoints afetados e aguarde aprovação humana explícita.
Enter fullscreen mode Exit fullscreen mode

O branch de IA torna esse bloqueio real: nenhuma alteração chega ao main antes da aprovação.

Atualizar a partir de um arquivo OpenAPI

Quando a alteração já existe em um arquivo OpenAPI — gerado a partir do código, mantido por outra equipe ou editado em outro sistema — use import em vez de atualizar cada campo manualmente.

apidog import --project <projectId> \
  --format openapi \
  --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

O comando aceita OpenAPI 3.x, Swagger 2.0, Postman e outros formatos.

Importe primeiro em um branch de IA, revise o diff e só então faça merge. Após a fusão, exporte a especificação para verificar o resultado reconciliado:

apidog export --project <projectId> \
  --format openapi \
  --oas-version 3.1 \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Use import quando a fonte de verdade estiver fora do Apidog. Use endpoint update ou schema update quando o Apidog for a fonte de verdade e a alteração for cirúrgica.

Rollback: descarte o branch

Se o agente gerar uma mudança incorreta, não faça merge. Arquive o branch:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> \
  --type ai
Enter fullscreen mode Exit fullscreen mode

Como a mudança nunca chegou ao main, não há rollback complexo. O branch é seu botão de desfazer.

Isso é muito mais seguro do que permitir atualizações diretas no main, onde um payload incorreto entra em vigor imediatamente e pode exigir reversão manual.

Permissões de edição

Se update ou import retornar bloqueado, as Permissões de Edição Externa de IA podem estar desativadas no projeto.

Nesse caso, use o fluxo com branch de IA: o agente altera um branch isolado e uma pessoa aprova o merge.

Se preferir habilitar edição direta, a configuração está em:

Configurações do Projeto
→ Configurações de Recursos
→ Configurações de Recursos de IA
Enter fullscreen mode Exit fullscreen mode

Essa opção está disponível no cliente Apidog 2.8.32 ou superior.

Quando o agente encontrar uma barreira de permissão, ele não deve buscar atalhos silenciosos. Ele deve reportar o bloqueio e pedir uma decisão humana.

Armadilhas comuns

Atualização parcial removeu campos

update substitui; não mescla.

Correção: busque o objeto completo, edite-o, valide-o e só então envie-o de volta.

Editar recurso existente em um branch de IA vazio

O branch de IA não contém automaticamente os recursos do branch de origem.

Correção: use pick-to antes de editar endpoints ou schemas existentes.

Usar um --from incorreto

A origem do branch de IA deve ser main ou um branch de sprint regular, não um branch geral.

Correção: valide sua estratégia de branches antes de criar o branch de IA.

Pular a validação

Sem cli-schema validate, um erro de digitação ou um payload malformado chega à API sem verificação local.

Correção: torne a validação uma etapa obrigatória antes de cada update.

Mesclar uma alteração incompatível sem aviso

Renomear ou remover um campo obrigatório pode quebrar clientes existentes.

Correção: exija a classificação de compatibilidade e bloqueie mudanças disruptivas até receber aprovação explícita.

FAQ

Posso deixar o agente editar o branch principal diretamente?

Pode, habilitando as Permissões de Edição Externa de IA. Mas iniciar com um branch de IA é mais seguro: nada chega ao main sem revisão e aprovação.

Reserve edição direta para automações de baixo risco e alta confiança.

Qual é a diferença entre branch merge e merge-request?

branch merge grava a mudança imediatamente e exige permissão de edição direta nos dois branches.

merge-request abre uma solicitação revisável, ideal quando o branch principal está protegido.

O agente precisa do aplicativo desktop do Apidog?

Não. A CLI é autônoma.

O aplicativo é necessário apenas para alterar a configuração de Permissões de Edição Externa de IA, caso você opte por habilitar edição direta.

Como evitar que o agente invente nomes de campos?

Faça o agente sempre seguir este ciclo:

get → modificar → validate → update
Enter fullscreen mode Exit fullscreen mode

A validação local detecta payloads com campos inválidos antes que eles cheguem ao projeto.

Conclusão

Atualizar uma especificação de API com um agente é seguro quando você aplica três controles:

  1. O agente trabalha em um branch de IA isolado.
  2. Toda atualização usa leitura-modificação-escrita do objeto completo.
  3. Um humano revisa e aprova o merge.

Com a CLI do Apidog, esse fluxo é programável e auditável. Uma alteração ruim não exige uma correção no main: basta arquivar o branch.

Configure o branch de IA, inclua a regra de atualização completa nas instruções do agente e exija aprovação para mudanças incompatíveis. Assim, a manutenção da especificação vira um diff revisável, em vez de uma tarefa manual e arriscada.

Baixe o Apidog para acessar a CLI e combine esse fluxo com a automação para criar documentação de API com um agente.

Top comments (0)