Como Usar um Agente de IA para Criar Documentação de API com a CLI do Apidog

A documentação de API é a tarefa que todos concordam ser importante e ninguém quer assumir. Um novo endpoint é lançado, a referência atrasa uma semana, e o guia de introdução descreve um fluxo de autenticação que você substituiu há dois sprints. O trabalho é real, mas é repetitivo e fácil de adiar.

Essa combinação (importante, repetitiva, adiável) é exatamente o que um agente de IA faz de melhor. Se seu agente pode executar um comando de terminal, ele pode criar endpoints, escrever os guias em prosa sobre eles e publicar um site de documentação, tudo a partir de uma solicitação em linguagem natural. A CLI do Apidog é o que torna isso possível: cada ação de documentação é um comando scriptável com saída JSON estruturada que um agente pode ler e agir.

botão

Por que a CLI, não a GUI ou um servidor MCP

Existem três maneiras pelas quais um agente pode interagir com a documentação da sua API, e elas resolvem problemas diferentes. Entender essa distinção é a diferença entre lutar com suas ferramentas e usar a que foi feita para o trabalho.

Abordagem	Direção	Quem a executa	Diff revisável?
GUI	Edições humanas em um navegador	Uma pessoa, clicando	Não
Servidor MCP	Lê sua especificação → escreve código	Um agente, em seu editor	No seu repositório de código, não na documentação
CLI	Escreve a própria documentação	Um agente, em um terminal	Sim, cada comando é registrado

Um servidor MCP é excelente quando você deseja que um agente leia sua definição de API e gere código cliente a partir dela. O fluxo de documentação via MCP do Cursor é o exemplo canônico. Mas isso é o inverso do que queremos aqui. Queremos que o agente produza a documentação: crie endpoints, escreva guias Markdown e publique um site.

Para isso, a CLI vence em três aspectos. É determinística: o mesmo comando produz o mesmo resultado. É scriptável: todo o fluxo se integra ao CI. E retorna JSON em cada chamada, incluindo um campo agentHints.nextSteps que informa ao agente o que ele pode fazer em seguida. Esse último ponto importa mais do que parece: significa que o agente não está adivinhando seu caminho, ele está seguindo as próprias sugestões da CLI.

Configure o ambiente do agente

Instale a CLI e autentique-se uma vez. Nosso guia de instalação cobre as versões do Node e o PATH; o guia de autenticação cobre tokens e segredos de CI.

npm install -g apidog-cli
apidog login --with-token <TOKEN>

Obtenha o token no aplicativo Apidog em avatar do usuário → Configurações da Conta → Token de Acesso à API. Ele é armazenado localmente após o login, para que o agente não precise passá-lo em cada chamada.

Cada escrita é executada contra um ID de projeto, que você encontrará em Configurações do Projeto → Configurações Básicas, ou executando:

apidog project list

Qualquer agente de codificação que possa executar comandos de shell funciona aqui: Claude Code, Cursor, Codex, e outros. A CLI não se importa com quem a está chamando; ela só se importa que os comandos e payloads estejam corretos. O que nos leva à única regra que torna tudo confiável.

O ritual de escrita que um agente deve seguir

Comandos de documentação que criam recursos usam um arquivo JSON. Seu agente nunca deve construir esse JSON manualmente da memória. Nomes de campos inventados pelo modelo são a principal causa de falhas. A CLI fornece o esquema exato para cada escrita, e a sequência correta é sempre a mesma, em quatro etapas:

# 1. Pergunte à CLI como é o payload
apidog cli-schema get doc-create

# 2. Gere o arquivo JSON a partir desse esquema

# 3. Valide antes de escrever (detecta um campo ausente localmente)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Só agora execute o comando real
apidog doc create --project <projectId> --file ./doc.json

Incorpore este ciclo nas instruções do agente. Isso transforma “o modelo inventou um campo” em “o validador o rejeitou em minha máquina”, o que é a diferença entre uma execução limpa e uma compilação falha. Aqui está um bloco de regras que você pode colar diretamente no prompt do sistema de um agente ou em um arquivo CLAUDE.md / .cursorrules:

Regras da CLI do Apidog:
- Nunca escreva um payload JSON manualmente. Execute `apidog cli-schema get ` primeiro e construa a partir desse esquema.
- Valide cada arquivo com `apidog cli-schema validate  --file ` antes de qualquer criação ou atualização.
- Sempre passe --project  em comandos de escrita.
- Leia o campo `agentHints.nextSteps` em cada resposta JSON para escolher o próximo comando.
- Se uma escrita for bloqueada por permissões, pare e pergunte ao humano; não tente uma solução alternativa.

Essas cinco linhas são o que separa um agente que entrega documentação de forma confiável de um que tenta payloads aleatórios até falhar.

Etapa 1: Crie a referência a partir de endpoints e esquemas

No Apidog, sua referência de API é gerada a partir dos endpoints e esquemas de dados do projeto. Portanto, a primeira tarefa do agente é criá-los. Suponha que você o instrua:

“Adicione um endpoint POST /refunds que receba um ID de pedido e um valor, e documente suas respostas de sucesso e de erro de validação.”

O agente cria primeiro o modelo de dados reutilizável, e depois o endpoint que o referencia. Executar apidog cli-schema get schema-create mostra que um esquema de dados aceita um name e um objeto jsonSchema padrão. Então o agente escreve algo como refund-schema.json:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}

Valide e crie:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Agora o endpoint. O esquema endpoint-create requer method e path, e permite que você referencie o modelo de dados que você acabou de criar com um $ref no formato #/definitions/{schemaId}. O agente escreve refunds-endpoint.json:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
  }
}

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json

A documentação de referência para /refunds agora existe, renderizada a partir da mesma definição que sua equipe edita. Não há uma etapa separada de “exportar a documentação” para a referência; ela está ativa no projeto no momento em que o endpoint é criado. Essa é a vantagem de uma fonte schema-first: a referência não pode divergir, porque ela é o esquema.

Etapa 2: Escreva os guias, não apenas a referência

Uma referência gerada a partir de esquemas é apenas metade de uma boa documentação. A outra metade é a prosa: uma página de introdução, um passo a passo de autenticação, uma nota de migração. No Apidog, elas residem na árvore de documentação do projeto como documentos Markdown, gerenciados pelo grupo de comandos doc.

O esquema doc-create requer apenas um name; content contém o Markdown, e folderId o posiciona na árvore (0 é a raiz). Então, um guia rápido que o agente elabora se torna quickstart.json:

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

É aqui que o agente prova seu valor. Peça para ele “escrever um guia rápido que leve um novo desenvolvedor de uma chave de API ao primeiro reembolso”, e ele elaborará o Markdown, o envolverá no payload que o esquema espera, validará e criará o documento. Sem navegador, sem copiar e colar. Como o conteúdo é apenas um campo de string, o agente pode escrever um guia tão longo ou detalhado quanto a tarefa exigir.

Etapa 3: Publique o site de documentação

Com a referência e os guias implementados, o agente também pode publicar a partir do terminal. Dois grupos de comandos lidam com isso, e uma distinção de nomes confunde as pessoas constantemente:

doc: um documento Markdown dentro da árvore da API do projeto (o que você criou na etapa 2).
docs-site: o site de documentação público e hospedado.
shared-doc: um link compartilhável para entregar a um parceiro, não um site completo.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json

Use docs-site quando quiser um site público definido a partir do terminal, e shared-doc quando precisar apenas de um link para enviar a alguém. Como ambos são comandos, a publicação se torna uma etapa scriptada que o agente executa após cada alteração de documentação; o site hospedado reflete a atualização no momento em que o comando retorna.

Etapa 4 (opcional): Exporte uma cópia portátil

Às vezes você quer a documentação como um arquivo: uma página HTML para hospedar em outro lugar, Markdown para um gerador de site estático, ou OpenAPI para entregar a sistemas posteriores. O comando export produz todos os três:

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json

Se seu projeto contém vários serviços e você quer documentar apenas uma parte dele, apidog export --help mostra as flags --scope, --api-ids e --folder-ids para refinar a saída. Um único projeto pode gerar um arquivo de documentação por serviço dessa forma.

Um exemplo completo, de ponta a ponta

Aqui está o ciclo completo como uma solicitação em linguagem natural e os comandos que um agente executa para satisfazê-la.

Você: “Acabamos de adicionar um serviço de pagamentos com POST /refunds e GET /refunds/{id}. Documente ambos, escreva um pequeno guia explicando chaves de idempotência, e publique-o em nosso site de documentação.”

O agente, seguindo suas regras, executa:

# Crie o modelo de dados compartilhado
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Crie ambos os endpoints
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Escreva o guia de idempotência como um documento Markdown
apidog doc create --project $PID --file ./idempotency-guide.json

# Publique
apidog docs-site create --project $PID --file ./docs-site.json

Você revisa o diff resultante, e o serviço de pagamentos está documentado e ativo. O que costumava ser uma tarde de troca de contexto é uma solicitação e uma revisão.

Integre-o a um loop de agente ou CI

Como cada etapa é um comando, todo o fluxo se integra ao CI ou ao loop de tarefas de um agente. Um passo mínimo que regenera e commita sua referência Markdown a cada push:

- name: Regenerar documentação da API
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md

Para uma visão mais completa de como executar um agente com a CLI de ponta a ponta, consulte Do PRD ao Loop de Testes e Como Configurar 5 Agentes de IA para Construir uma API Completa. O padrão em ambos é o mesmo aqui: descreva a intenção, deixe o agente traduzi-la em chamadas CLI validadas, revise o resultado.

Uma nota sobre permissões

A escrita em um projeto por meio de um agente pode ser controlada. Se um comando create retornar bloqueado, o projeto tem as Permissões de Edição Externa por IA desativadas para aquele branch. Você tem duas opções honestas: habilitar a permissão de edição direta em Configurações do Projeto → Configurações de Recurso → Configurações de Recurso de IA (cliente Apidog 2.8.32+), ou fazer com que o agente trabalhe em um branch de IA isolado e abra uma solicitação de merge. O guia complementar sobre como atualizar sua especificação de API detalha o fluxo do branch de IA, e isso se aplica igualmente quando o agente está criando documentação em um branch protegido.

Armadilhas comuns

O agente construiu o JSON manualmente. Esta é a falha número um. Force cli-schema get → cli-schema validate → create nas instruções do agente para que ele trabalhe com o esquema real, não com um adivinhado.
ID de projeto ausente. Toda chamada doc, docs-site e export precisa de --project <projectId>, o ID das configurações, não o nome legível do projeto. A maioria dos relatórios de “erro” é devido a isso.
Confusão entre doc, docs-site e shared-doc. São três coisas diferentes: uma página Markdown na árvore, um site hospedado e um link de compartilhamento. Faça o agente confirmar qual deles a tarefa se refere antes de escrever.
Token não configurado no CI. apidog login armazena o token na máquina que o executa. Um runner de CI novo não tem nenhum, então execute login --with-token no mesmo job antes de qualquer comando, e mantenha o token em um segredo.
Um $ref que aponta para lugar nenhum. Quando um endpoint referencia um modelo de dados com #/definitions/{schemaId}, esse esquema precisa existir primeiro. Crie os esquemas antes dos endpoints que os utilizam.

Perguntas Frequentes

Quais agentes de IA podem usar a CLI do Apidog? Qualquer agente que possa executar comandos de shell: Claude Code, Cursor, Codex e agentes de codificação semelhantes. A CLI é agnóstico a agentes; ela só precisa de comandos corretos e payloads válidos.
Preciso de um plano pago? Não. O Apidog não é de código aberto, mas o nível gratuito mais o apidog-cli cobrem o fluxo de criação e publicação descrito aqui.
O agente pode sobrescrever documentos existentes por acidente? create adiciona novos recursos. A modificação de recursos existentes usa update, que se comporta de forma diferente e precisa de suas próprias salvaguardas; isso é abordado no guia complementar sobre como atualizar sua especificação de API.
Em que isso difere de um gerador de documentação de IA? Ferramentas genéricas de documentação de IA produzem texto a partir do seu código. Isso produz documentação estruturada dentro da sua plataforma de API (endpoints, esquemas, guias e um site publicado) a partir de uma única fonte viva que não pode divergir do que sua equipe edita.

Conclusão

Um agente que pode executar a CLI do Apidog pode assumir a parte da documentação que as pessoas sempre adiam: ele cria os endpoints, escreve os guias relacionados e publica o site. Tudo a partir de uma solicitação em linguagem natural, com validação de esquema protegendo cada escrita. Seu papel muda de escrever documentação para revisar um diff.

A única regra que o torna confiável é o ritual de escrita: obtenha o esquema, valide e depois crie. Dê ao seu agente esse ciclo, o bloco de regras de cinco linhas acima e um ID de projeto, e a documentação deixa de ser uma tarefa que fica para trás do código. Baixe o Apidog para obter a CLI, ou leia o guia completo da CLI do Apidog para a referência completa de comandos.

botão