Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

7.3 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

Spring REST Docs — 공식 프로젝트 페이지

Layer: raw/official-docs/ — Spring 공식 프로젝트 페이지 verbatim 발췌. ca-tmpl 결정 (OpenAPI drift via springdoc + JSON snapshot) 의 대안 평가용.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-contract-verification-test-suite	ca-tmpl 의 "OpenAPI drift: springdoc-openapi 생성 vs checked-in snapshot diff" 결정에 대한 대안 (test-driven docs via REST Docs) 비교 근거

컨텍스트 / 왜 저장했는지

feature-contract-verification-test-suite 의 ca-tmpl 결정은 "OpenAPI drift: springdoc-openapi 생성 vs checked-in snapshot diff". 대안인 Spring REST Docs 는 test-driven docs 접근으로, snapshot 이 아니라 test 실행으로 docs 조각을 만든다. 두 접근의 trade-off 를 명문화하려고 보관.

출처 / Source

원본 URL: https://spring.io/projects/spring-restdocs
아카이브 URL: (미수집)
저자 / 조직: Spring (VMware / Broadcom)
발행일: 지속적으로 갱신
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim, 2026-05-27 확인)

[§Overview, 2026-05-27 verified] "It combines hand-written documentation written with Asciidoctor and auto-generated snippets produced with Spring MVC Test"

[§Differentiation, 2026-05-27 verified] "This approach frees you from the limitations of the documentation produced by tools like Swagger"

[§Output quality, 2026-05-27 verified — partial] "produce documentation that is accurate, concise, and well-structured" (현 페이지는 정확성 보장 메커니즘 을 명시하지 않음 — test-driven generation 이 정확성을 보장한다는 직접 문장 부재)

부재 확인 (2026-05-27):

이전 캡처 "Spring REST Docs enables test-driven documentation by embedding API tests into your documentation workflow." → 현 페이지에서 동일 wording 미발견. paraphrase 였을 가능성. claim 작성 시 해당 문장은 evidence 로 사용 금지.
이전 캡처 "This guarantees documentation accuracy by tying it directly to test execution." → 현 페이지에서 동일 wording 미발견. "guarantee" 라는 강한 표현이 페이지에 없음. claim 시 강도 하향 필요.

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SRD-C1	Spring REST Docs 는 hand-written Asciidoctor 문서와 Spring MVC Test 가 자동 생성한 snippet 을 결합한다	[§Overview, 2026-05-27 verified] "It combines hand-written documentation written with Asciidoctor and auto-generated snippets produced with Spring MVC Test"	`official-vendor-doc`	Spring MVC 기반 프로젝트의 REST API 문서화	Spring WebFlux / non-MVC 스택에서 동일하게 동작한다는 뜻은 아님 — 본 인용은 MVC Test 명시
SRD-C2	이 접근은 Swagger 같은 도구가 생성하는 문서의 한계로부터 자유롭다는 vendor 주장	[§Differentiation, 2026-05-27 verified] "This approach frees you from the limitations of the documentation produced by tools like Swagger"	`official-vendor-doc`	annotation-driven docs (Swagger / springdoc-openapi) 와의 대비 의사결정	Swagger 가 어떤 구체 한계를 가진다는 직접 enumeration 부재 — vendor 의 일반적 marketing 진술 수준
SRD-C3	Spring REST Docs 의 출력 목표는 accurate / concise / well-structured 문서	[§Output quality, 2026-05-27 verified] "produce documentation that is accurate, concise, and well-structured"	`official-vendor-doc`	REST Docs 의 docs 품질 목표 표현	정확성을 보장 (guarantee) 한다는 직접 문장 부재 — 본 페이지는 "guarantee" 단어 미사용. drift detection 메커니즘으로서의 신뢰성은 별도 검증 필요

부재 claim (NOT FOUND 처리):

Candidate Claim	Status	Reason
"REST Docs 가 test-driven documentation 을 enable 한다" 직접 문장	NOT FOUND (2026-05-27)	이전 캡처의 wording 이 현 페이지에 없음 — paraphrase 였을 가능성. claim 미생성
"test execution 과 tie 해서 정확성을 guarantee 한다" 직접 문장	NOT FOUND (2026-05-27)	"guarantee" 라는 강한 표현이 페이지에 부재. claim 미생성

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- SRD-C1: hand-written Asciidoctor + Spring MVC Test snippet 결합 모델 (official vendor 의 공식 product description)
- SRD-C2: Swagger 류 도구와의 차별화를 vendor 가 주장 (단, 구체적 한계 enumeration 부재)
- SRD-C3: 출력 docs 의 품질 목표 (accurate/concise/well-structured) — 단 "보장" 이 아닌 "목표"
이 자료가 증명하지 않는 것:
- REST Docs 가 OpenAPI drift detection 의 release-blocking gate 역할을 한다는 직접 보장 — REST Docs 는 docs 생성 도구이지 drift gate 가 아님. drift gate 는 build-time spec diff 가 별도 책임
- REST Docs 가 springdoc-openapi 보다 항상 우월하다는 비교 — 본 자료는 단일 vendor 페이지이며 비교 평가 부재
- REST Docs 가 OpenAPI 3.x spec 을 first-class 로 생성한다는 직접 명시 (snippets → spec 변환은 별도 extension restdocs-api-spec 필요)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 release-blocking drift gate 요구사항을 REST Docs 가 충족하는지 (test fail → docs 미생성 → build fail 의 chain 이 실제로 강제되는지)
- REST Docs 로 OpenAPI spec 을 first-class 산출하려면 restdocs-api-spec extension 필요 — 본 페이지 범위 밖
- 외부 공개 API docs 품질을 위해 REST Docs 를 추가 로 도입할 때 springdoc 과의 양립 운영 비용

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

ca-tmpl 이 springdoc-openapi (annotation-driven generation) 를 택한 이유: annotation 은 항상 코드와 함께 변경되므로 drift 탐지를 build 에서 release-blocking gate 로 강제하기 쉬움.
REST Docs 는 사람이 쓰는 docs 품질 이 핵심 가치 (SRD-C1). skeleton 단계에서는 docs 품질보다 "release blocking 에서 drift 를 잡는 것" 이 우선이므로 ca-tmpl 결정과 결이 다름.
향후 외부 공개 API docs 가 필요해지면 REST Docs 를 추가 로 도입할 수 있음 (springdoc 과 양립 가능 — 단 운영 비용 검증 필요).

적용 branch-note:
- raw/branch-notes/feature-contract-verification-test-suite
canonical contract 섹션:
- raw/project-notes/ca-skeleton-operational-contract#12. Test Contract
대안 그룹: Group G-G — Skeleton Governance (verification)
본 source 의 위치: 대안 2 — Spring REST Docs (test-driven docs 대안)

7.3 KiB Raw Permalink Blame History