Files

T

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

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

9.5 KiB

Raw 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

OpenAPI snapshot diff — springdoc / openapi-diff / Tufin oasdiff

Layer: raw/official-docs/ — 공식 문서 발췌. OpenAPI snapshot generation + diff 의 도구 체인 baseline.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-ci-quality-gates-contract	OpenAPI drift gate — "ground truth = code-generated snapshot (springdoc 등). hand-maintained 는 forbidden." 결정의 도구 근거
raw/branch-notes/feature-api-compatibility-deprecation-contract	breaking change catalog row + `intent:breaking-change-approved` label escape hatch 의 자동 검출 backend
raw/branch-notes/feature-schema-serialization-contract	schema drift gate 가 같은 도구 체인 (oasdiff / openapi-diff) 을 공유 가능하다는 사실

특정 branch 없이 foundational 조사로 수집한 경우:

raw/project-notes/ca-skeleton-operational-contract — ca-tmpl 의 API contract test 도구 선정 자료

컨텍스트 / 왜 저장했는지

feature-ci-quality-gates-contract 결정 "OpenAPI drift ground truth = code-generated snapshot (springdoc 등). hand-maintained 는 forbidden." 의 도구 근거. ./gradlew openapiCheckSnapshot 이 실재 가능한 task 인지, breaking change 판정을 어떤 도구가 어떻게 하는지 raw 로 확보.

출처 / Source

원본 URL:
- springdoc-openapi — https://springdoc.org/
- OpenAPITools/openapi-diff (Maven Central + GitHub) — https://github.com/OpenAPITools/openapi-diff
- Tufin/oasdiff — https://github.com/Tufin/oasdiff
- OpenAPI Specification 3.1 — https://spec.openapis.org/oas/v3.1.0
아카이브 URL: (미수집)
저자 / 조직: springdoc community, OpenAPITools, Tufin, OpenAPI Initiative
발행일: 공식 문서 (지속 갱신, fetched 2026-05-27)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[springdoc-openapi §How it works] "springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations."

[springdoc-openapi §Features] "Automatically generates documentation in JSON/YAML and HTML format APIs."

[springdoc-openapi §Features] "The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info."

[OpenAPITools/openapi-diff README] "Compare two OpenAPI specifications (3.x) and render the difference to HTML plain text, Markdown files, or JSON files."

[Tufin/oasdiff README] "Command-line and Go package to compare and detect breaking changes in OpenAPI specs."

[Tufin/oasdiff README §Usage] "Swap changelog for breaking to see only breaking changes, or diff for the full machine-readable diff."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
CIOS-C1	springdoc-openapi 는 runtime 에 application 을 검사하여 spring configuration / class 구조 / annotation 으로부터 API semantic 을 추론한다	[springdoc-openapi §How it works] "springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations."	`official-vendor-doc`	Spring Boot + springdoc-openapi 환경	runtime 검사이므로 dynamic routing (e.g., WebFlux functional routes) 의 일부가 누락될 수 있음 — 인용은 누락 가능성을 직접 언급하지 않음
CIOS-C2	springdoc-openapi 는 JSON / YAML / HTML 형식으로 자동 문서 생성을 지원한다	[springdoc-openapi §Features] "Automatically generates documentation in JSON/YAML and HTML format APIs."	`official-vendor-doc`	API docs 생성 워크플로우	어떤 endpoint (`/v3/api-docs`, `/swagger-ui.html`) 에 노출되는지의 정확한 path 는 본 인용에 없음
CIOS-C3	springdoc-openapi 는 Spring Boot auto-configured package 를 사용하여 Spring bean 의 `OpenAPIDefinition` / `Info` annotation 을 스캔한다	[springdoc-openapi §Features] "The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info."	`official-vendor-doc`	Spring Boot auto-configuration 활성 환경	non-Spring-Boot (plain Spring) 에서의 동작은 본 인용 범위 밖
CIOS-C4	OpenAPITools/openapi-diff 는 두 OpenAPI 3.x 사양을 비교하고 HTML / plain text / Markdown / JSON 형식으로 차이를 렌더링한다	[OpenAPITools/openapi-diff README] "Compare two OpenAPI specifications (3.x) and render the difference to HTML plain text, Markdown files, or JSON files."	`official-vendor-doc`	OpenAPI 3.x snapshot 비교 시나리오	breaking vs non-breaking 의 정확한 판정 규칙은 본 인용에 명시 없음 — README 의 별도 섹션에서 확인 필요
CIOS-C5	Tufin/oasdiff 는 OpenAPI 사양의 비교와 breaking change 검출을 위한 CLI + Go package 이다	[Tufin/oasdiff README] "Command-line and Go package to compare and detect breaking changes in OpenAPI specs."	`official-vendor-doc`	CI 통합 (CLI 호출) 또는 Go application 임베드	exit code 가 breaking 시 non-zero 인지의 정확한 동작은 본 인용에 명시 없음 — `breaking` 서브명령의 정확한 exit semantic 확인 필요
CIOS-C6	oasdiff 는 `changelog` (전체 변화) / `breaking` (breaking only) / `diff` (machine-readable) 3가지 서브명령을 제공한다	[Tufin/oasdiff README §Usage] "Swap `changelog` for `breaking` to see only breaking changes, or `diff` for the full machine-readable diff."	`official-vendor-doc`	oasdiff CLI 호출 패턴 설계	각 서브명령의 출력 schema / JSON 구조는 본 인용 범위 밖

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- CIOS-C1 ~ C3: springdoc-openapi 의 runtime introspection 동작 원리 및 출력 형식
- CIOS-C4: OpenAPITools/openapi-diff 가 OpenAPI 3.x 비교 + 다중 포맷 렌더링을 지원한다는 사실
- CIOS-C5, CIOS-C6: oasdiff 가 CLI + Go package 형태로 breaking change 검출을 제공하며 3개 서브명령을 가진다는 사실
이 자료가 증명하지 않는 것:
- 두 diff 도구 (openapi-diff vs oasdiff) 의 정확한 breaking change 판정 규칙 차이 (어떤 변경을 breaking 으로 보는가)
- springdoc 이 WebFlux functional routes 또는 Spring Cloud Gateway 의 dynamic route 를 어떻게 처리하는가
- ./gradlew openapiCheckSnapshot 같은 Gradle task 가 어떤 plugin 으로 구현되는가 (springdoc-openapi-gradle-plugin 의 정확한 task 이름과 config 는 별도 페이지)
- 두 도구의 CI exit code semantic — --fail-on-breaking 같은 flag 의 존재 여부
- OpenAPI 3.1 vs 3.0 spec 차이가 두 도구의 동작에 미치는 영향
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 build.gradle 에 springdoc-openapi-gradle-plugin 추가 시 정확한 task 명 (generateOpenApiDocs 추정)
- 어느 diff 도구를 채용할지 — oasdiff (Go binary, k8s-friendly) vs openapi-diff (Maven Central, JVM-native 통합 용이) 선택 기준
- breaking change 정의 정책 — "intent:breaking-change-approved" label escape hatch 와 도구 exit code 의 연결
- openapi-snapshot.yaml 의 checkin 위치 및 PR diff review 워크플로우

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

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

실행 가능한 체인:
1. springdoc 이 런타임에 /v3/api-docs 생성 → Gradle task 가 build 시점에 파일로 dump.
2. Tufin/oasdiff 또는 OpenAPITools/openapi-diff 로 openapi-snapshot.yaml (checked-in) vs build artifact 비교.
3. breaking change 1건이라도 있으면 exit code != 0 → CI fail. 단, exit code semantic 은 도구별 flag 확인 필요 (CIOS-C5 가 직접 보장하지 않음).
ca-tmpl 결정의 "./gradlew openapiCheckSnapshot exit code 0 verify" 는 위 체인을 한 Gradle task 로 합성하면 성립. Spring Initializr 기본 archetype 에는 없으므로 별도 task 정의 필요.
함정: springdoc 은 controller annotation 을 정적 추출하므로 dynamic routing (예: webflux functional routes) 이 있으면 누락 위험. branch note 의 "ground truth" 라는 표현은 이 범위 내에서만 참 — 본 springdoc 공식 페이지는 누락 위험을 직접 명시하지 않음, 일반적 통념.

같은 주제 다른 official-doc:
- raw/official-docs/ci-github-actions-vs-gitlab-comparison — CI backend 매핑
적용 branch-note:
- raw/branch-notes/feature-ci-quality-gates-contract — OpenAPI drift gate
- raw/branch-notes/feature-api-compatibility-deprecation-contract — breaking change catalog row + intent:breaking-change-approved label escape hatch
- raw/branch-notes/feature-schema-serialization-contract — schema drift gate 가 같은 도구 체인을 공유 가능

9.5 KiB Raw Blame History