Files
clean-architecture-backend-…/docs/web/openapi-32-compatibility.md
DongHyeonka 9d6c67c14e docs(web): web 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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 등 주석).
2026-11-07 17:29:57 +09:00

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를 다룬다.