Editar uma especificação de API manualmente é um trabalho meticuloso. Renomear um campo, adicionar um valor de enum, apertar uma flag de obrigatoriedade. Cada mudança é pequena, mas cada uma precisa ser feita no lugar certo sem quebrar os endpoints que a referenciam. É preciso, mecânico e exatamente o tipo de tarefa que você entregaria a um agente de IA, se pudesse confiar que ele não bagunçaria todo o esquema.
Você pode. A CLI do Apidog dá a um agente tudo o que ele precisa para mudar uma especificação de forma responsável: validação de esquema antes de cada gravação, um branch isolado para trabalhar e uma solicitação de merge para você revisar.
Este é o companheiro de mutação para permitir que um agente crie documentação de API. Criar é aditivo e de baixo risco; atualizar um contrato existente é onde as salvaguardas importam, então a maior parte deste guia é sobre como fazer isso sem quebrar as coisas.
O que "atualizar a especificação" significa na CLI
Sua especificação no Apidog é o conjunto de endpoints e esquemas de dados em um projeto. Atualizá-la significa um dos três comandos:
endpoint update: mudar um caminho, um parâmetro, uma resposta.schema update: mudar um modelo de dados que os endpoints referenciam.import: trazer um arquivo OpenAPI completamente novo para reconciliar com o projeto.
Antes de apontar um agente para qualquer um deles, existem dois comportamentos que você precisa entender, porque cometer erros com eles é como uma especificação pode ser danificada. O primeiro é um modelo de permissão, e o segundo é uma pegadinha que silenciosamente apaga dados.
A pegadinha que vai te morder: update é uma substituição completa
Esta é a coisa mais importante a ensinar ao seu agente. Os comandos update da CLI não são JSON Patch. Eles enviam os campos que você fornece diretamente; eles não mesclam itens de array por ID. Se você enviar uma atualização com um array parameters parcial pretendendo mudar um parâmetro, você não edita esse parâmetro. Você substitui o array inteiro apenas pelo que você enviou, e o resto se perde.
A sequência correta é sempre ler-modificar-escrever no objeto completo:
# 1. Obtenha o recurso completo atual
apidog endpoint get <endpointId> --project <projectId>
# 2. Edite a estrutura completa localmente (mantenha todos os campos que você não está alterando)
# 3. Valide o objeto inteiro contra o esquema
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json
# 4. Escreva o objeto completo de volta
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json
Coloque isso nas instruções do agente em termos claros: nunca envie um objeto parcial para update; sempre busque o recurso completo, modifique-o e envie-o de volta inteiro. Um agente que pula a etapa get descartará campos silenciosamente. Um agente que executa cli-schema validate primeiro pega seus próprios erros antes que eles cheguem ao projeto.
O caminho seguro: deixe o agente trabalhar em um branch de IA
Você poderia dar ao agente permissão de edição direta em seu branch principal. Não faça isso, pelo menos não para começar. O Apidog tem um mecanismo de isolamento construído especificamente, o branch de IA, projetado exatamente para isso: um agente modifica recursos sem tocar no branch de origem, e nada é mesclado de volta até que você diga sim. Pense nisso como uma solicitação de pull para sua especificação de API.
Passo 1: Crie o branch de IA
apidog branch create --project <projectId> --type ai \
--from main --name "ai/20260713-from-main-refund-fields"
A convenção de nomenclatura é ai/AAAA-MM-DD-da-origem-funcionalidade para que a origem e o propósito do branch sejam legíveis de relance. O valor --from deve ser seu branch principal ou um branch de sprint normal, não um branch geral. Um detalhe útil: um branch de IA sem diferença de sua origem é arquivado automaticamente após 24 horas, então experimentos abandonados se limpam.
Passo 2: Importe os recursos que o agente editará
Um branch de IA começa vazio. Ele não clona o branch de origem automaticamente. Antes que o agente possa editar um endpoint ou esquema existente, puxe esse recurso para o branch com pick-to:
apidog branch pick-to --project <projectId> --type ai \
--from main --to "ai/20260713-from-main-refund-fields" \
--endpoint-ids <ids>
Recursos que o agente cria novos no branch não precisam disso; apenas os existentes que ele pretende modificar ou excluir. Esta é a etapa que as pessoas esquecem: pule-a, e o agente terá um branch vazio e nada para editar.
Passo 3: Deixe o agente fazer a mudança
Agora o agente executa o loop de leitura-modificação-escrita de antes, mas com --branch apontando para o branch de IA. Cada edição é contida:
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
Seu branch principal permanece intocado durante todo esse tempo. Se o agente errar algo, o raio de impacto é um branch descartável.
Passo 4: Revise, depois mescle
As mudanças no branch de IA nunca são escritas de volta automaticamente. Quando o agente termina, você decide o que acontece. Se o destino estiver protegido, abra uma solicitação de merge em vez de mesclar diretamente:
apidog merge-request --help
apidog branch merge --project <projectId> --type ai \
--from "ai/20260713-from-main-refund-fields" --to main --endpoint-ids <ids>
Revise o diff, aprove, e a mudança verificada será aplicada no main. A fusão direta pela CLI requer permissão de edição direta em ambos os branches de origem e destino; se o branch main estiver protegido, prefira merge-request e o aprove no cliente Apidog.
Um exemplo prático: renomeando um campo com segurança
Regras abstratas são fáceis de concordar e difíceis de aplicar. Aqui está uma concreta. Digamos que você queira renomear amount para amountCents no modelo de dados Refund, porque você está migrando para centavos inteiros.
Você diz ao agente: "Renomeie o campo amount no esquema Refund para amountCents e torne-o um inteiro." Seguindo suas regras, o agente:
# 1. Busca o esquema COMPLETO atual no branch de IA
apidog schema get <refundSchemaId> --project $PID --branch "ai/20260713-from-main-refund-fields"
Ele recebe de volta o objeto completo e edita o todo jsonSchema, mantendo cada campo que ele não está tocando:
{
"name": "Refund",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amountCents"],
"properties": {
"orderId": { "type": "string" },
"amountCents": { "type": "integer" },
"reason": { "type": "string" }
}
}
}
Observe o que não aconteceu: ele não enviou apenas a propriedade alterada. Ele enviou o esquema inteiro com orderId e reason intactos, porque update substitui. Então:
# 2. Valida o objeto completo
apidog cli-schema validate schema-create --file ./refund-full.json
# 3. Escreve de volta para o branch de IA
apidog schema update <refundSchemaId> --project $PID \
--branch "ai/20260713-from-main-refund-fields" --file ./refund-full.json
Você revisa o diff do branch de IA (um campo renomeado, nada mais perturbado) e mescla. Essa é toda a disciplina: objeto completo, validado, em um branch, mesclado após revisão.
Sinalize mudanças que quebram a compatibilidade antes de mesclar
Renomear um campo obrigatório é uma mudança que quebra a compatibilidade: qualquer cliente que enviar amount agora falhará na validação. Um bom conjunto de instruções para o agente faz com que o modelo diga isso em vez de mesclar silenciosamente. Adicione isso às regras do agente:
Antes de mesclar qualquer alteração de especificação, classifique-a:
- Não disruptiva (novo campo opcional, novo endpoint, restrição flexibilizada) → resuma e prossiga para a solicitação de merge.
- Disruptiva (campo renomeado/removido, novo campo obrigatório, tipo mais restrito) → PARE.
Relate a alteração disruptiva e os endpoints afetados, e aguarde aprovação humana explícita.
O branch de IA é o que torna isso seguro de impor: como nada é mesclado automaticamente, "parar e relatar" é um ponto de verificação real, não uma corrida contra uma escrita que já aconteceu.
Atualizando a partir de um arquivo OpenAPI, em vez disso
Às vezes, a mudança já existe como um arquivo OpenAPI, gerado a partir do código, editado em outro lugar ou entregue por outra equipe. Em vez de repetir as edições campo por campo, o agente pode importar o arquivo para reconciliá-lo com o projeto:
apidog import --project <projectId> --format openapi --file ./openapi.json \
--branch "ai/20260713-from-main-refund-fields"
import aceita OpenAPI 3.x, Swagger 2.0, Postman e muito mais. Execute-o primeiro em um branch de IA para que você possa revisar o que a especificação de entrada muda antes que chegue ao main. Depois de mesclar, exporte a especificação reconciliada de volta para confirmar o resultado:
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Essa rota é melhor quando a fonte da verdade vive fora do Apidog e você está sincronizando-a. A rota de update por campo é melhor quando o Apidog é a fonte da verdade e você está fazendo uma mudança cirúrgica.
Quando o agente erra: rollback
A razão para trabalhar em um branch de IA é que os erros são baratos para desfazer. Se o agente produzir uma mudança que você não quer, você nunca a mesclou, então o main já está correto. Apenas arquive o branch e siga em frente:
apidog branch archive "ai/20260713-from-main-refund-fields" --project <projectId> --type ai
Como um branch de IA sem diferença aceita é arquivado automaticamente após 24 horas de qualquer forma, até mesmo um experimento esquecido se limpa. Compare isso com um agente editando o main diretamente, onde um update ruim está ativo imediatamente e seu único recurso é a lixeira ou uma reversão manual. O branch não é burocracia; é o botão de desfazer.
Uma nota sobre permissões
Se um update ou import retornar bloqueado, o projeto tem as Permissões de Edição Externa de IA desativadas. Essa é uma barreira deliberada, e o fluxo de branch de IA acima é a resposta para isso: o agente edita um branch isolado e você aprova o merge. Se preferir conceder edições diretas, a chave está em Configurações do Projeto → Configurações de Recursos → Configurações de Recursos de IA (Apidog client 2.8.32+). Quando um agente encontra uma barreira de permissão, não o faça escolher uma solução alternativa silenciosamente; apresente a escolha a um humano.
Armadilhas comuns
Atualização parcial apagou campos. O erro mais prejudicial e mais comum. update substitui; não mescla. Busque o objeto completo, edite-o por inteiro, valide e depois escreva. Se um campo desapareceu, o agente enviou um payload parcial.
Editando um recurso existente em um branch de IA sem importá-lo. O branch começa vazio. pick-to o recurso primeiro, ou o agente não terá nada para editar.
--from errado para o branch de IA. A origem deve ser main ou um branch de sprint, nunca um branch geral. O comando branch create reclamará se você errar isso.
Pulando a validação. cli-schema validate detecta um payload malformado em sua máquina. Um agente que escreve sem validar transforma um erro de digitação em uma chamada de API falha, ou pior, um merge inválido.
Mesclando uma alteração que quebra a compatibilidade silenciosamente. Sem uma regra de classificação prévia, um agente renomeará um campo obrigatório e o mesclará sem problemas. Faça da detecção de alterações que quebram a compatibilidade um ponto de verificação explícito.
FAQ
Posso deixar o agente editar o branch principal diretamente? Você pode, habilitando as Permissões de Edição Externa de IA, mas começar em um branch de IA é mais seguro: nada vai para o main até que você aprove um merge. Reserve as edições diretas para automação de baixo risco e alta confiança.
Qual a diferença entre branch merge e merge-request? branch merge escreve a mudança imediatamente e precisa de permissão de edição direta em ambos os branches. merge-request abre uma solicitação revisável, a escolha certa quando o main está protegido.
O agente precisa do aplicativo de desktop Apidog? Não, a CLI é autônoma. O aplicativo só importa para alternar a configuração de Permissões de Edição Externa de IA, que é uma configuração única.
Como garantir que o agente não "alucine" o nome de um campo? O loop cli-schema get → validate é a salvaguarda. Um payload com um campo inventado falha na validação localmente, antes mesmo de chegar ao projeto.
Conclusão
Permitir que um agente atualize sua especificação de API é seguro quando três coisas são verdadeiras: ele trabalha em um branch de IA isolado, ele trata cada atualização como uma leitura-modificação-escrita completa em vez de um patch, e um humano aprova o merge. A CLI do Apidog oferece todos os três como comandos, o que significa que todo o loop (editar, validar, revisar) é programável e auditável, e uma mudança ruim está a um archive de distância de ser eliminada.
Configure o branch de IA, entregue ao agente a regra de leitura-modificação-escrita e o ponto de verificação de alterações que quebram a compatibilidade, e a manutenção da especificação se torna um diff que você aprova em vez de um trabalho meticuloso que você continua adiando. Baixe o Apidog para obter a CLI, e combine isso com permitir que um agente crie sua documentação para cobrir todo o ciclo de autoria e manutenção.