OpenAPI 다국어 SDK 코드젠 — 스펙이 SoT

"설명서 한 권으로, 여러 나라 말로 된 사용법 책을 자동으로 찍어내기" 예요. 우리 서버(기계)를 남들이 쓰려면 사용법이 필요한데, 사용법을 언어마다 손으로 베껴 쓰면 반드시 어긋나요. 그래서 원본 설명서 하나만 잘 만들고, 나머지 언어판은 버튼 눌러 자동으로 인쇄해요.

비유: 레고 조립 설명서 📘

우리 서버가 레고 세트라고 생각해 봐요. 다른 사람이 조립하려면 설명서가 필요해요.

원본 설명서(OpenAPI 문서) = "이 서버는 이런 부품(데이터)이 있고, 이렇게 조립(호출)한다"를 적은 딱 하나의 원본이에요. 이게 세상에서 제일 정확한 진짜예요.
언어판 사용법 책(SDK) = 그 원본을 넣고 버튼을 누르면, 한국어판·영어판·자바판·파이썬판 사용법이 자동으로 인쇄돼 나와요. 사람이 번역 안 해요.
자동 인쇄본은 손대지 마세요 = 인쇄본에 볼펜으로 낙서하면, 다음에 다시 인쇄하는 순간 낙서가 싹 사라져요. 고치고 싶으면 항상 원본 설명서를 고쳐야 해요.
부품을 바꾸면 설명서도 같이 = 레고 부품 하나를 바꿨으면, 그 자리에서 설명서도 새로 뽑아 함께 내놔요. 부품 따로, 설명서 따로 두면 남들이 옛날 설명서로 조립하다 망가져요.

원본 하나 → 여러 언어판 자동 인쇄

서버를 바꾸면 벌어지는 일

부품을 바꾸는 것과 설명서를 새로 뽑는 건 항상 한 세트로 움직여야 해요.

이렇게 하면 "서버는 바뀌었는데 사용법 책은 옛날 그대로"인 사고(이걸 어려운 말로 drift 라고 해요)가 안 나요.

트레이드오프도 쉽게: 가벼운 인쇄기를 쓰면 빠르고 간단하지만 만들 수 있는 언어판이 적고, 무거운 인쇄기를 쓰면 자바·파이썬 등 여러 언어를 다 뽑을 수 있지만 준비가 무거워요. 그래서 흔한 언어는 가벼운 걸로 빨리 뽑고, 다른 언어는 무거운 인쇄기도 열어 둬요 — 원본 설명서 하나는 똑같이 공유하면서요.

핵심만 다시

사용법은 원본 설명서 하나만 진짜예요. 나머지 언어판은 거기서 자동 인쇄돼요.
자동 인쇄본은 손대지 말기 — 다시 뽑으면 손댄 게 다 사라져요. 고칠 땐 원본을 고쳐요.
서버를 바꾸면 설명서도 같이 새로 뽑아 항상 딱 맞게 유지해요.
열쇠(토큰) 넣는 일은 한 곳에서만 챙겨서, 쓰는 사람이 매번 신경 안 쓰게 해요.

더 자세한 진짜 코드·설계는 옆의 개요 / Variants / Apply Recipe 탭에서 볼 수 있어요.