OpenAPI 오버레이

OpenAPI Overlays

원본 API 설명을 직접 수정하지 않고 별도 작업 목록을 적용해 문서를 보강합니다.

···
html
<div class="viz"><h3>SOURCE + OVERLAY</h3><div class="row"><div class="box">GET /orders</div><span class="arrow">+</span><div class="box" id="overlay">audience: partner</div><span class="arrow">→</span><div class="box" id="result">GET /orders<br>partner</div></div><div class="muted">source document stays the same</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}#overlay{color:var(--accent-2)}#result{min-width:29%;border-color:var(--accent)}#overlay.off{opacity:.2}#result.off{border-color:var(--line)}
js
let enabled=true;function draw(){enabled=!enabled;document.getElementById('overlay').classList.toggle('off',!enabled);document.getElementById('result').classList.toggle('off',!enabled);document.getElementById('result').innerHTML=enabled?'GET /orders<br>partner':'GET /orders'}draw();setInterval(draw,1700)

OpenAPI Overlay는 대상 문서의 노드를 선택하고 순서대로 갱신·삭제·복사할 수 있는 별도 문서입니다. 원본 설명은 유지하면서 팀별 설명, 태그, 배포 환경에 맞는 문서 보강을 적용할 수 있습니다. 액션은 앞선 액션의 결과에 이어 적용됩니다.

데모는 원본 GET /orders 설명에 오버레이를 켰을 때 audience 태그와 설명이 합쳐지는 모습을 보여줍니다. 변환 결과도 검증해야 하며, 원본과 오버레이의 책임을 명확히 구분해야 합니다.

언제 쓰나

외부에서 받은 명세나 공용 명세를 유지하면서 팀별 설명을 덧붙일 때 씁니다.

페이지로 열기 ↗