OpenAPI Streaming Media Types

OpenAPI 스트리밍 미디어 표현

OpenAPI 3.2 describes responses whose items arrive sequentially, including JSON Lines and 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)

A normal JSON response is parsed after the whole document arrives, while a streaming media type yields items in sequence. OpenAPI 3.2 can describe individual sequential items with itemSchema and covers event streams such as SSE. Consumers can display each arrival without waiting for completion.

The demo compares one complete JSON block with events arriving over time. Real streams also need rules for disconnection, partial messages, and reconnection.

When to use

Use it when documenting SSE or JSON Lines items for consumers and tooling.

Open as page ↗