문제: - application-notification·-fileserver·-objectstorage는 가장 가까운 AGENTS가 루트뿐이고 README가 없었다. web-notification·web-fileserver·redis-runtime도 자기 AGENTS·README가 없었다. 그 leaf를 고치는 세션은 지역 규칙(전송이 이름을 짓지 않음, 포화 코드의 갈림, callback 경로가 절대 경로인 이유 등)을 볼 곳이 없었다. - docs/README.md 지도의 security/ 행이 rate-limiting.md를 덮지 않았다. - shared-contract AGENTS 책임 목록이 PageMeta·ResponseMeta·Category·공용 carrier 예외 셋·ServerFailureLog·ActiveTrace를 빠뜨렸다. - docs/web/repository-adaptation.md가 「애플리케이션 칸은 강제하지 않는다」고 했지만 web은 JSON 본문 1 MiB(app.web.mvc.max-json-body-size, 413)를 강제한다. - openapi-32-compatibility.md가 아무도 만들지 않는 3.1.2 릴리스 산출물과 3.1 snapshot 불변식을 이 repo의 것처럼 적었다(샘플 삭제 뒤). 고친 것: leaf 여섯에 AGENTS.md(등록 정보, 책임, 규칙, 시험)·CLAUDE.md(@AGENTS.md)· README.md(책임과 소유하지 않는 것, 공개 표면, 조립, 시험 명령, 더 읽을 곳)를 쓰고, 규칙의 정본은 가리키기만 했다. 지도 행, shared-contract 책임 목록, 본문 한도 표와 머리말, OpenAPI 문서를 고쳤다. 순서: 새 leaf 문서가 계약 PR(batch bulk envelope, 알림 VALIDATION_FAILED, SERVER_BUSY, 전송이 이름을 짓지 않음)의 동작을 적는다. 그 PR 뒤에 병합한다. 검증: check-docs.py·check-work-docs.py rc=0. Refs: RR9-04-35, RR9-04-36, RR9-04-42
30 lines
1.9 KiB
Markdown
30 lines
1.9 KiB
Markdown
# OpenAPI 3.2: 실험 lane
|
|
|
|
## 업그레이드가 아니라 lane인 이유
|
|
|
|
3.2를 만드는 것은 싸다. 받아들이는 것은 싸지 않다. 만든 문서가 멀쩡해 보여서 둘이 섞인다.
|
|
|
|
API 설명의 가치는 전부 그것을 소비하는 쪽에 있다. client generator가 다 이해하지 못하는 버전의 문서는 실패하지
|
|
않는다. 컴파일되는데 틀린 client를 만든다. 문서가 아예 없는 것보다 나쁘다.
|
|
|
|
그래서 3.2는 3.1 문서를 바꾸지 않고 그 옆에서 만든다. 이 템플릿 자체는 OpenAPI 문서를 릴리스 산출물로 내지
|
|
않는다(만들던 샘플을 2026-09-25에 지웠다). 아래는 3.1 문서를 내는 서비스가 3.2를 함께 만들 때의 규칙이다.
|
|
|
|
## 불변식
|
|
|
|
**3.2를 만드는 것이 그 서비스의 3.1 문서를 바꾸면 안 된다.** 둘은 같은 모델에서 나온다. 그래서 3.2로 가는 길에
|
|
모델을 바꾸는 기여자는 실제로 내보내는 산출물을 바꾼다. 조용히, 그리고 3.2를 만들 때만. 서비스는 자기 3.1 문서를
|
|
snapshot으로 두고 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도 OpenAPI 문서를 만들지 않는다. `OpenApiVersionLane.STABLE_3_1`은 서비스가 내보낼 안정
|
|
lane의 이름이고, `WebOpenApi32GeneratorTest`가 3.2 generator를 다룬다.
|