API 응답 JSON을 마크다운 표로 변환하기 — curl·jq, 페이지네이션, 6가지 패턴

Q: API 응답이 배열이 아닌 단일 객체일 때는 어떻게 표로 만드나요?

응답이 { "id": 1, "name": "Alice" } 형태의 단일 객체라면 두 가지 방법이 있습니다. 첫째, 최상위를 [{ ... }]로 감싸 헤더 1행, 데이터 1행인 가로형 표로 만드는 방법입니다. 둘째, 속성(Key)과 값(Value) 두 개의 열로 구성된 세로형 2열 테이블로 재구성하는 방법입니다. 단일 객체 설정값이나 상세 프로필을 문서화할 때는 세로형 표가 가독성에 더 유리합니다.

API 응답을 README나 Issue, 사내 위키(Wiki), PR(Pull Request) 등에 공유할 때, 가공되지 않은 원시(Raw) JSON 데이터는 한눈에 파악하기 어려워 마크다운 표(Markdown table)로 정리하고 싶은 경우가 자주 있습니다. 이 글에서는 curl로 호출한 API 응답 JSON을 브라우저만으로 안전하게 마크다운 표로 변환하는 절차를 다룹니다. 페이지네이션(Pagination), 중첩 객체, 최상위가 배열이 아닌 경우 등 실무에서 마주치는 다양한 예외 케이스 처리법도 함께 정리합니다.

API 응답을 마크다운 표로 변환하는 가장 빠른 경로는 "curl로 응답 가져오기 → jq로 객체 배열 추출 → CSV 형태로 변환 → CSV to Markdown에서 표 생성"입니다. 배열 형태가 아닌 응답은 jq를 사용해 대상 배열로 내려가거나 [ ... ]로 감싼 뒤 처리합니다. 모든 변환 과정이 브라우저 내부에서 로컬로 완결되므로, 인증 토큰(Authorization Bearer)이나 민감한 정보가 포함된 응답 데이터도 외부 서버로 전송되지 않아 안전합니다.

결론: API 응답은 "배열 추출"로 표가 됩니다

API 응답 JSON을 마크다운 표로 만들 수 있는지 여부는 "동일한 구조를 가진 객체들의 배열로 추출할 수 있는가"에 달려 있습니다. 실제 상용 API는 다음과 같이 메타데이터와 함께 반환되는 경우가 많아, 그대로는 바로 표로 만들 수 없습니다.

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

여기서 표로 만들고자 하는 핵심 데이터는 data 필드 안에 들어 있는 객체 배열입니다. 최상위에서 data 배열로 접근한 뒤 이를 CSV 형식으로 변환하여 전달하면, 깔끔한 열 헤더와 데이터 행을 갖춘 마크다운 표를 얻을 수 있습니다.

워크플로: curl + jq + FormatArc

가장 효율적인 전체 파이프라인을 명령어 흐름으로 정리하면 다음과 같습니다. 각 단계마다 중간 출력을 눈으로 직접 확인하며 진행할 수 있습니다.

# 1. API를 호출해 JSON 파일로 저장
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.example.com/v1/users > users.json

# 2. JSON 포맷터에 붙여넣어 계층 구조 확인
#    https://formatarc.com/ko/json-formatter/

# 3. data 배열만 추출해 CSV 형식으로 변환
jq -r '.data | (map(keys) | add | unique) as $cols
       | $cols, (.[] | [.[$cols[]]]) | @csv' users.json

# 4. 출력된 CSV를 CSV to Markdown에 붙여넣어 마크다운 표 생성
#    https://formatarc.com/ko/csv-to-markdown/

jq를 설치하지 않고 브라우저에서 바로 구조를 확인하고 싶다면, JSON 응답을 JSON 포맷터에 붙여넣어 계층 구조와 키 이름을 먼저 파악하는 것부터 시작할 수 있습니다.

1단계: API 응답 수집 및 정렬

브라우저에서 직접 열 수 있는 GET 엔드포인트라면, 네트워크 탭에서 응답을 복사해 JSON 포맷터에 붙여넣는 것만으로 깔끔하게 정렬할 수 있습니다. 터미널에서 curl을 사용할 때는 -s 옵션으로 진행 상태 표시를 숨기고, 필요에 따라 -H 옵션으로 인증 헤더를 추가합니다.

응답을 파일로 저장해 두면 jq 필터를 여러 번 수정하며 원하는 출력을 안전하게 맞출 수 있습니다.

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은 jq가 설치되어 있지 않은 환경에서도 기본 내장된 Python만으로 빠르게 JSON을 정렬해 볼 수 있는 방법입니다. 자세한 명령어와 정렬 방법은 curl JSON 정렬 방법을 참고하세요.

2단계: 배열 추출 및 CSV 생성

정렬된 JSON을 확인하여 "동일한 형태의 객체 배열이 어떤 키 경로에 있는지"를 파악합니다. 대표적인 API 응답 구조는 다음과 같습니다.

API 응답 구조	표로 만들 배열 위치	jq 추출 식
`[ {...}, {...} ]` (최상위가 배열)	최상위(루트)	`.`
`{ "data": [ ... ] }`	`data`	`.data`
`{ "items": [ ... ], "next": "..." }`	`items`	`.items`
`{ "results": { "users": [ ... ] } }`	`results.users`	`.results.users`

추출하려는 배열 경로를 확인했다면, 다음과 같이 jq 명령어를 실행해 CSV를 생성합니다.

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

이 jq 식은 배열 내 모든 객체에 등장하는 모든 키를 수집(map(keys) | add | unique)하여 CSV 열 헤더($cols)를 만들고, 각 객체의 값을 헤더 순서와 동일하게 행 단위로 출력합니다. 특정 객체에 일부 키가 빠져 있어도 오류 없이 빈 셀로 처리됩니다. 또한 @csv 필터는 값 안에 쉼표(,)나 줄바꿈이 포함된 경우 자동으로 큰따옴표("...")로 감싸 주므로, CSV to Markdown에 붙여넣었을 때 열이 어긋나지 않습니다.

3단계: CSV to Markdown으로 마크다운 표 생성

2단계에서 얻은 CSV 텍스트를 복사하여 CSV to Markdown 변환기에 붙여넣고 실행합니다.

FormatArc CSV to Markdown에서 API 응답으로 마크다운 표 생성

생성된 출력은 GFM(GitHub Flavored Markdown) 표준 규격을 따르므로 GitHub README, Issue, PR 설명, Notion, velog, Tistory, Slack 등 마크다운을 지원하는 대부분의 플랫폼에 그대로 붙여넣어 사용할 수 있습니다. 표의 서식이나 세부 작성 문법은 마크다운 표 작성법을 참고하세요.

API 응답 패턴별 변환 난이도

API마다 반환하는 JSON 구조가 다르기 때문에 마크다운 표로 변환하는 난이도도 달라집니다. 주요 응답 형태별 난이도와 처리 핵심을 정리합니다.

API 유형	응답 구조	변환 난이도	처리 핵심
단순 목록(List) API	`[ { ... } ]` 평탄한 배열	낮음	`.`로 배열을 그대로 전달
래핑된 컬렉션	`{ "data": [ { ... } ] }`	낮음	`.data`로 대상 배열에 진입
페이지네이션 적용 API	`{ "items": [ ... ], "next_cursor": "..." }`	중간	페이지별 응답을 jq로 병합 후 추출
중첩된 객체 포함	`{ "user": { "name": ... }, "stats": { ... } }`	중간	점 표기법(dot notation)으로 키를 생성해 평탄화
GraphQL 응답	`{ "data": { "users": { "edges": [ { "node": { ... } } ] } } }`	높음	`.data.users.edges[].node`로 노드 배열 추출
서로 다른 형태의 객체 혼재	`[ { type: "A", ... }, { type: "B", ... } ]`	높음	type별로 필터링한 뒤 각각 별도 표로 생성

변환 시 핵심 원칙은 단순합니다. 가장 먼저 "동일한 키 구조를 가진 객체 배열로 잘라낼 수 있는가"를 확인하고, 구조가 복잡하다면 JSON 포맷터에서 전체 계층을 펼쳐 보며 대상 경로를 특정합니다.

페이지네이션 API 응답을 하나의 표로 병합하기

커서(Cursor) 방식이나 페이지 번호(Page number) 방식을 사용하는 API는 페이지마다 동일한 구조의 배열을 반환합니다. jq의 --slurp(-s) 옵션을 사용하면 여러 페이지의 응답 JSON 파일을 단일 배열로 합쳐 한 번에 표로 만들 수 있습니다.

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 옵션은 각 파일의 JSON을 하나의 최상위 배열로 묶고, [.[] | .data[]]는 각 응답의 data 배열 요소들을 순서대로 꺼내어 단일 배열로 결합합니다. 이후 동일한 jq 표현식을 거쳐 하나의 CSV로 출력되며, 이를 CSV to Markdown에 입력하면 전체 데이터가 합쳐진 마크다운 표가 완성됩니다.

중첩된 JSON은 "평탄화(Flatten)"로 처리하기

사용자 정보 안에 주소 객체가 중첩되어 있는 것과 같은 계층형 JSON은, 그대로 표로 변환하면 특정 셀에 {...} 형태의 JSON 텍스트가 그대로 들어가 가독성이 떨어집니다. 점 표기법(dot notation)을 사용해 키를 평탄화하는 것이 좋습니다.

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

이 상태로 변환하면 address 열에 원시 객체 문자열이 들어가지만, jq를 통해 키를 평탄화하면 읽기 쉬운 형태로 펼쳐집니다.

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

실행 결과는 id, name, address.city, address.zip의 4개 열을 가진 CSV가 됩니다. 이를 CSV to Markdown에 전달하면 중첩 구조가 포함된 API 응답도 깔끔한 표로 변환됩니다. 만약 tags: ["a", "b"]와 같이 배열 필드가 포함되어 있다면 join("|") 등을 사용해 하나의 셀 안에 문자열로 묶어 주면 표가 깨지지 않습니다.

브라우저만으로 안전하게 변환하고 싶을 때

API 응답에는 인증 토큰(Bearer Token), 사용자 개인정보, 내부 데이터베이스 식별자 등이 포함되는 경우가 많습니다. 이러한 데이터를 외부 변환 사이트에 업로드하는 것은 보안 및 개인정보 유출 위험이 있습니다.

FormatArc의 모든 데이터 변환 처리는 브라우저 내부에서만 실행되며 서버로 데이터를 전송하지 않습니다. 자세한 동작 원리와 보안 비교는 온라인 변환 사이트 보안 검증을 참고하세요.

브라우저만으로 작업을 완결하는 절차는 다음과 같습니다.

curl 대신 브라우저 개발자 도구(F12)의 Network 탭에서 API 응답 JSON을 복사합니다.
JSON 포맷터에 붙여넣어 구조와 계층을 확인합니다.
필요한 키만 남긴 객체 배열 형태로 정리한 후 CSV로 구성합니다.
CSV to Markdown에 붙여넣어 최종 마크다운 표를 생성합니다.

데이터의 행 수가 많지 않다면 터미널이나 jq 없이 브라우저 도구의 조합만으로도 충분히 빠르고 안전하게 변환할 수 있습니다.

자주 겪는 문제와 해결 방법

API 응답을 마크다운 표로 변환할 때 자주 발생하는 문제와 대응 방법입니다.

응답이 배열이 아닌 단일 객체인 경우: 최상위를 [ ... ]로 감싸 1행짜리 배열로 만들거나, 키(Key)와 값(Value) 2개 열로 이루어진 수직형 표로 변환합니다. 자세한 변환 방법은 JSON to Markdown Table 변환 방법을 참고하세요.
일부 객체에 특정 키가 누락된 경우: jq의 add | unique 패턴을 사용하면 전체 객체에 존재하는 모든 키를 헤더로 수집하고, 누락된 값은 빈 셀("")로 안전하게 채워집니다.
값 안에 파이프(|) 또는 줄바꿈이 포함된 경우: CSV 단계에서는 @csv가 자동으로 큰따옴표 처리를 해 주지만, 마크다운 표로 변환할 때 셀 안의 파이프 문자는 \|로 이스케이프해야 열 구분이 깨지지 않습니다. 자세한 대처법은 마크다운 표가 깨질 때의 대처법을 참고하세요.
대형 정수 ID의 정밀도 손실: 64비트 정수 ID를 숫자로 다루면 자바스크립트나 파서에서 반올림으로 정밀도가 손실될 수 있습니다. jq에서 tostring을 사용해 문자열로 유지하는 것이 안전합니다.
문자 깨짐(인코딩 오류): 압축 응답이나 UTF-8 인코딩 불일치일 수 있으므로 curl 호출 시 curl --compressed를 추가하거나 UTF-8 인코딩으로 변환 후 포맷터에 붙여넣습니다.

자주 묻는 질문

API 응답이 배열이 아닌 단일 객체일 때는 어떻게 표로 만드나요?

응답이 { "id": 1, "name": "Alice" } 형태의 단일 객체라면 두 가지 방법이 있습니다. 첫째, 최상위를 [{ ... }]로 감싸 헤더 1행, 데이터 1행인 가로형 표로 만드는 방법입니다. 둘째, 속성(Key)과 값(Value) 두 개의 열로 구성된 세로형 2열 테이블로 재구성하는 방법입니다. 단일 객체 설정값이나 상세 프로필을 문서화할 때는 세로형 표가 가독성에 더 유리합니다.

jq 설치 없이 브라우저에서 바로 JSON을 마크다운 표로 바꿀 수 있나요?

가능합니다. 브라우저 개발자 도구에서 복사한 JSON을 JSON 포맷터에 붙여넣어 필요한 객체 배열 부분만 추려낸 뒤, CSV 형태로 정리하여 CSV to Markdown에 전달하면 됩니다. 데이터 규모가 작다면 별도 CLI 도구 설치 없이 브라우저만으로 충분히 완료할 수 있습니다.

API 응답에 인증 토큰이나 개인정보가 포함되어 있어도 온라인 도구를 써도 되나요?

서버로 데이터를 업로드하는 일반적인 온라인 변환 사이트는 보안상 피해야 합니다. 반면 FormatArc는 모든 변환 로직이 사용자의 웹 브라우저 로컬(Client-side)에서만 실행되며 입력 데이터가 서버로 일절 전송되지 않으므로, 인증 토큰이나 내부 데이터가 포함된 API 응답도 안전하게 처리할 수 있습니다.

대용량 API 응답도 마크다운 표로 변환할 수 있나요?

마크다운 표 자체는 텍스트 기반이므로 수백 행 수준은 원활하게 렌더링되지만, 수천 행이 넘어가면 GitHub이나 렌더러의 페이지 로딩이 느려질 수 있습니다. 대용량 데이터는 jq에서 .[:50]과 같이 상위 50~100개 행만 잘라내어 예시 표로 마크다운에 싣고, 전체 데이터는 CSV나 JSON 파일 링크로 첨부하는 방식을 권장합니다.

정리

API 응답 JSON을 마크다운 표로 만드는 핵심은 동일한 형태의 객체 배열을 추출하는 것입니다.
curl로 수집하고 jq로 객체 배열을 CSV로 구성한 뒤 CSV to Markdown에 전달하면 가장 안정적으로 표가 생성됩니다.
페이지네이션 응답은 jq의 --slurp(-s)를 사용해 하나로 묶을 수 있고, 중첩 객체는 점 표기법으로 평탄화합니다.
FormatArc의 모든 변환은 브라우저 내부에서만 동작하므로 민감한 API 응답 데이터도 안전하게 변환할 수 있습니다.