문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는 짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외). repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다. - 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에, `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다. `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다. - Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()` (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다. - 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다. - 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다. - 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다. 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로 둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과 문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다. 버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한 대응이 사라진다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는 주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
1.6 KiB
OpenAPI 3.2: 실험 lane
업그레이드가 아니라 lane인 이유
3.2를 만드는 것은 싸다. 받아들이는 것은 싸지 않다. 만든 문서가 멀쩡해 보여서 둘이 섞인다.
API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지 않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다.
그래서 3.1.2가 릴리스 산출물로 남고, 3.2는 그 옆에서 만든다.
불변식
3.2를 만드는 것이 3.1 snapshot을 바꾸면 안 된다. 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에 모델을 바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만.
이 저장소에는 그것을 검사하는 것이 더는 없다. snapshot을 hash하고 어떤 parser, linter, generator, client 컴파일이
3.2 출력을 읽었는지 기록하던 승격 보고서 OpenApi32CompatibilityReport와 OpenApiToolchainMatrix는 2026-09-25에
지웠다. production 코드에 있었고 자기 테스트만 그것을 불렀다. WebOpenApi32Generator(라이브러리,
adapter:inbound:web-advanced)로 3.2를 만드는 서비스는 그 검사를 자기 빌드에서 가진다.
승격은 판단으로 남고, docs/adr/ADR-WEB-ADV-003-openapi-32-remains-experimental.md에 기록한다.
돌리기
이 저장소의 어떤 workflow도 3.2를 만들지 않는다. OpenApiVersionLane.STABLE_3_1이 릴리스 산출물이고,
WebOpenApi32GeneratorTest가 generator를 다룬다.