Tabela Markdown a partir de uma resposta JSON de API — curl, jq e o navegador

Quando você quer colar uma resposta de API em um README, uma issue ou uma wiki interna, o JSON cru é difícil de ler — o que você realmente quer é uma tabela Markdown. Este guia mostra como chegar a essa tabela a partir de uma resposta de curl, incluindo os casos que costumam travar: paginação, objetos aninhados e respostas que nem chegam a ser arrays.

O caminho mais curto é "curl no endpoint → recortar o array com jq → passar por CSV → processar com CSV para Markdown". Respostas que não são arrays são recortadas até o array que interessa, ou envolvidas em [ ... ] antes da conversão. Tudo roda no navegador, então cabeçalhos de autenticação e dados sensíveis nunca saem da sua máquina.

A resposta curta: recorte o array e converta depois

Se uma resposta JSON de API vira uma tabela Markdown depende de uma única pergunta: dá para recortá-la até um array de objetos com o mesmo formato? A maioria das APIs reais devolve algo assim, que por si só não é uma tabela.

{
  "data": [
    { "id": "usr_001", "email": "mika@example.com", "active": true },
    { "id": "usr_002", "email": "noah@example.com", "active": false }
  ],
  "pagination": { "page": 1, "total": 2 }
}

O que você quer como tabela é o data. Desça até esse array primeiro e depois passe ao CSV; o resultado é uma tabela Markdown com cabeçalhos e linhas limpos.

O fluxo: curl + jq + FormatArc

Aqui está a cadeia inteira em uma sequência de comandos. Ela é pensada para você conferir a saída entre os passos, em vez de confiar em uma única caixa-preta.

# 1. Chamar a API e salvar o JSON
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/users > users.json

# 2. Colar no Formatador JSON para confirmar a estrutura
#    https://formatarc.com/pt/json-formatter/

# 3. Recortar o array data e montar um CSV
jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

# 4. Colar o CSV no CSV para Markdown e gerar a tabela
#    https://formatarc.com/pt/csv-to-markdown/

Se você precisa ajustar o próprio curl ou tornar a resposta crua legível, Como formatar JSON do curl cobre quatro formas de fazer isso. Se preferir pular o jq, dá para começar colando a resposta no Formatador JSON e moldar a partir daí.

Passo 1: obter a resposta e formatar

Para um endpoint GET acessível pelo navegador, copie a resposta direto no Formatador JSON. Com curl, -s esconde a barra de progresso e -H carrega o cabeçalho de autenticação.

Salvar a resposta em arquivo é o que torna o resto fácil — você pode rodar o jq de novo quantas vezes quiser.

curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/users > users.json
cat users.json | python3 -m json.tool | head

python3 -m json.tool é o formatador de dependência mínima para ambientes sem jq. Para o conjunto completo de one-liners, veja o guia de formatação de JSON com curl.

Passo 2: recortar o array e montar o CSV

Olhe para o JSON formatado e identifique "qual chave guarda o array de objetos com o mesmo formato". Os formatos comuns são estes.

Escolha o recorte certo e monte um CSV a partir dele.

jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

Essa expressão jq coleta toda chave que aparece no array, usa-as como linha de cabeçalho e escreve os valores de cada objeto na mesma ordem. Objetos sem alguma chave aparecem como célula vazia, sem erro em tempo de execução. @csv também cuida de valores com vírgula ou quebra de linha — embrulha em "..." para o CSV colar limpo no CSV para Markdown sem quebrar colunas.

Passo 3: converter o CSV em tabela Markdown

Cole o CSV em CSV para Markdown e rode a conversão.

A saída é compatível com GFM (GitHub Flavored Markdown), então entra direto em arquivos README, issues do GitHub, documentos do Notion ou entradas Markdown do Slack. Se precisar ajustar a tabela à mão depois, Sintaxe de tabelas Markdown cobre as regras no nível da spec.

Formatos de resposta classificados por dificuldade de conversão

Cada API devolve um formato diferente, e a dificuldade de virar tabela Markdown segue esse formato. Aqui está uma matriz de dificuldade para comparar com o seu endpoint.

A decisão é a mesma em todo caso: confirme que dá para recortar até um array de objetos com o mesmo formato. Se não dá, volte para o Formatador JSON e encontre o caminho de chave que leva até lá.

Juntando respostas paginadas em uma tabela só

APIs com cursor ou número de página devolvem o mesmo formato de array em cada página. A flag --slurp (-s) do jq combina vários arquivos JSON em um único array, então o resto do pipeline continua funcionando.

for page in 1 2 3; do
  curl -s "https://api.example.com/v1/users?page=$page" > "page-$page.json"
done

jq -s '[.[] | .data[]]
       | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' page-*.json

-s envolve o JSON de cada arquivo em um array externo, e .[] | .data[] percorre o data de cada resposta e concatena os elementos. A partir daí, o mesmo pipeline jq monta um CSV único que você cola em CSV para Markdown.

Ache os objetos aninhados antes de converter

Se sua resposta traz um registro de usuário com um endereço aninhado, deixá-lo como está coloca {...} na célula, o que é ilegível. Achate com chaves pontuadas.

[
  {
    "id": "usr_001",
    "name": "Mika",
    "address": { "city": "Tokyo", "zip": "100-0001" }
  }
]

jq -r '.[] | {id, name, "address.city": .address.city, "address.zip": .address.zip}
       | [.id, .name, ."address.city", ."address.zip"]
       | @csv' users.json

O CSV agora tem quatro colunas: id, name, address.city, address.zip. Cole em CSV para Markdown e os campos aninhados pousam em colunas próprias. Para arrays aninhados (tags: ["a", "b"]), juntá-los com join("|") deixa cada linha em uma só linha.

Quando você quer manter tudo no navegador

Respostas de API costumam carregar cabeçalhos de autenticação, dados de clientes ou IDs internos, então colá-las em um conversor de terceiros é difícil de justificar. O FormatArc roda a conversão no navegador e nunca envia a entrada para um servidor. O detalhe do mecanismo, com uma comparação com conversores hospedados, está em Os conversores online são seguros para JSON sensível?.

Um fluxo puramente no navegador fica assim:

1. Em vez de curl, copie a resposta do DevTools (aba Network)
2. Cole no Formatador JSON e confira a estrutura
3. Deixe só as chaves necessárias e reorganize o array como CSV
4. Leve o CSV para CSV para Markdown e gere a tabela

Para arrays pequenos, dar forma ao CSV à mão é viável mesmo sem jq.

Pontos onde costumam travar

Estas são as situações que tendem a descarrilar o fluxo.

• A resposta é um único objeto, não um array: envolva como [ ... ] ou converta em uma tabela de duas colunas chave/valor. Como converter JSON em tabela Markdown cobre os dois caminhos
• Alguns objetos não têm todas as chaves: o padrão add | unique do jq pega toda chave que aparece em qualquer objeto, e as faltantes ficam como células vazias
• Valores com quebra de linha ou pipes (|): @csv coloca aspas no lado CSV, mas no Markdown final os pipes ainda precisam virar \|. Como consertar uma tabela Markdown quebrada repassa os escapes
• IDs numéricos grandes perdem precisão: APIs que devolvem IDs como números são truncadas em JavaScript. Use tostring do jq para o CSV guardá-los como strings
• Caracteres mal codificados: tente curl --compressed, ou passe o corpo por iconv -f UTF-8 antes de colar no Formatador JSON

Guias de conversão relacionados

• Como formatar JSON do curl — quatro formas (jq, Python, FormatArc, navegador) de formatar a saída do curl
• Como converter JSON em tabela Markdown — conversão geral de JSON para tabela, não específica de API
• Como converter CSV em tabela Markdown — por que o CSV é um bom formato intermediário
• Dicas para formatar JSON — ordenar chaves e ajustar arrays para tornar a estrutura legível

Referências

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• GitHub Flavored Markdown Spec — Tables (extension)
• Manual do jq