OpenAPI 스트리밍 미디어 표현

OpenAPI Streaming Media Types

OpenAPI 3.2에서 JSON Lines와 SSE처럼 항목이 순차 도착하는 응답을 기술합니다.

···
html
<div class="viz"><h3>COMPLETE vs STREAM</h3><div class="row"><div class="box lane">JSON<div class="track" id="whole"><i></i></div><small>one complete body</small></div><div class="box lane">SSE<div class="events" id="events"><i></i><i></i><i></i></div><small>items arrive in order</small></div></div></div>
css
.viz{width:94%;height:88%;max-width:960px;padding:clamp(10px,2vmin,18px);border:1px solid var(--line);border-radius:14px;background:var(--surface);font:600 clamp(12px,1.35vw,16px)/1.35 var(--font-sans,system-ui,sans-serif);display:flex;flex-direction:column;gap:clamp(7px,1.8vmin,13px);overflow:hidden}.viz h3{margin:0;color:var(--accent);font:700 clamp(12px,1.35vw,16px)/1.2 var(--font-sans,system-ui,sans-serif);letter-spacing:.04em}.viz .row{display:flex;align-items:center;justify-content:center;gap:clamp(5px,1.4vmin,12px);flex:1;min-height:0}.viz .box{padding:clamp(5px,1.5vmin,12px);border:1px solid var(--line);border-radius:9px;background:var(--bg);text-align:center}.viz .muted{color:var(--muted)}.viz .accent{color:var(--accent)}.viz .code{font-family:ui-monospace,monospace}.viz .pill{padding:3px 7px;border:1px solid var(--line);border-radius:99px;white-space:nowrap}.viz .active{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 12%,var(--surface))}.viz .arrow{color:var(--accent);font:700 18px ui-monospace,monospace}.lane{width:46%;height:90%;display:flex;flex-direction:column;justify-content:space-around;gap:5px}.lane small{font-size:12px;color:var(--muted)}.track,.events{height:24px;display:flex;gap:4px}.track i,.events i{display:block;background:var(--accent);border-radius:3px;transition:opacity .25s,transform .25s}.track i{width:100%}.events i{flex:1}.events i.off,.track i.off{opacity:.12;transform:scaleY(.4)}
js
let n=0;function draw(){document.querySelector('#whole i').classList.toggle('off',n<3);document.querySelectorAll('#events i').forEach((el,i)=>el.classList.toggle('off',i>=n));n=(n+1)%4}draw();setInterval(draw,650)

일반 JSON 응답은 전체 문서를 받은 뒤 파싱하지만 스트리밍 미디어는 조각을 차례로 처리합니다. OpenAPI 3.2는 순차 미디어의 개별 항목 구조를 itemSchema로 기술할 수 있고, SSE 같은 이벤트 스트림도 다룹니다. 소비자는 전체 완료를 기다리지 않고 도착한 항목을 표시할 수 있습니다.

데모에서는 한 덩어리 JSON과 이벤트가 시간차로 나타나는 스트림을 비교합니다. 실제 스트림에서는 연결 종료, 부분 메시지, 재연결 규칙을 별도로 정해야 합니다.

언제 쓰나

SSE나 JSON Lines API의 응답 항목을 명세와 코드 생성 도구에 알려야 할 때 씁니다.

페이지로 열기 ↗