109 lines
9.5 KiB
Markdown
109 lines
9.5 KiB
Markdown
---
|
|
title: OpenAPI snapshot diff — springdoc / openapi-diff / Tufin oasdiff
|
|
source_type: official-doc
|
|
url: https://springdoc.org/
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ci, openapi, contract-test, api-versioning, ca-skeleton, official-doc, branch:feature-ci-quality-gates-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-ci-quality-gates-contract, feature-api-compatibility-deprecation-contract, feature-schema-serialization-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# 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 공식 페이지는 누락 위험을 직접 명시하지 않음, 일반적 통념**.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 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 가 같은 도구 체인을 공유 가능
|