파이프라인 개요

이 파이프라인은 GitHub Actions(validate-and-release.yml)를 통해 매일 UTC 오전 6시에 실행되며, scripts/, config/, 또는 pyproject.toml을 변경하는 main 브랜치로의 모든 푸시 시에도 실행됩니다. 또한 릴리스를 강제하거나 라이브 API 테스트를 건너뛰는 옵션과 함께 수동으로 트리거할 수도 있습니다.

파이프라인 단계

 Download         Validate          Spectral Lint
 ┌──────┐        ┌──────────┐      ┌─────────────┐
 │ Fetch │───────▶│Schemathesis│────▶│  Discover   │
 │ specs │        │Constraints│     │  violations │
 └──────┘        └──────────┘      └─────────────┘
                                          │
                 Spectral Gate       Reconcile
                ┌─────────────┐    ┌──────────┐
                │  Enforce    │◀───│Apply fixes│
                │  thresholds │    │to specs   │
                └─────────────┘    └──────────┘
                       │
                    Release
                 ┌──────────┐
                 │  Package  │
                 │  & tag    │
                 └──────────┘

1. 다운로드

scripts/download.py는 docs.cloud.f5.com에서 공식 F5 XC OpenAPI 스펙 ZIP 파일을 가져옵니다. HTTP ETag 헤더를 사용한 조건부 GET 요청을 수행하며, 업스트림 번들이 변경되지 않았으면 다운로드를 건너뜁니다. 추출된 JSON 스펙은 specs/original/에 저장됩니다.

2. 검증

scripts/validate.py는 라이브 F5 XC API에 대해 두 가지 종류의 테스트를 수행합니다:

Schemathesis — 스펙에 따라 무작위 유효/무효 페이로드를 생성하고 API가 스펙의 제약 조건에 일치하는지 확인하는 속성 기반 테스팅입니다.
제약 조건 검증 — 10가지 OpenAPI 제약 조건 카테고리(문자열 길이, 패턴, 숫자 범위, 필수 필드, 열거형, 배열 범위, 객체 구조, 합성, 의존성, 데이터 타입) 모두에 대한 집중 테스트입니다.

불일치 사항은 reports/validation_report.json에 기록됩니다.

3. Spectral 린트 (발견)

scripts/spectral_lint.py --mode discover는 spectral-pipeline.yaml을 사용하여 원본 스펙에 대해 Spectral CLI를 실행합니다. 이를 통해 OAS3 품질 이슈를 찾습니다 — 누락된 servers 블록, 누락된 contact 정보, 태그 미지정 오퍼레이션, 사용되지 않는 컴포넌트 스키마, 중복 operationId, 유효하지 않은 예제, 설명 내 script 태그 등입니다.

위반 사항은 Discrepancy 객체로 변환되어 reports/spectral_report.json에 기록됩니다. 전체 규칙 세트는 Spectral 규칙을 참조하세요.

4. 조정

scripts/reconcile.py는 두 리포트 파일을 모두 소비하고 모든 스펙에 수정 사항을 적용합니다:

제약 조건 수정은 관찰된 API 동작을 기반으로 스키마 제약 조건을 조정합니다(완화, 강화, 추가, 제거). 적용된 수정 사항을 참조하세요.
Spectral 수정은 스펙에 servers, contact 정보, 태그, 보안 메타데이터를 보강하고 사용되지 않는 컴포넌트를 제거합니다.
보안 메타데이터는 security_scheme 설정이 존재하면 Spectral이 플래그를 지정하지 않았더라도 항상 주입됩니다.

수정된 스펙은 release/specs/에 기록되며, 저장하기 전에 openapi-spec-validator로 검증됩니다. 수정된 스펙이 검증에 실패하면 원본이 폴백으로 사용됩니다.

5. Spectral 게이트

scripts/spectral_lint.py --mode gate는 release/specs/의 조정된 스펙에 대해 Spectral을 재실행합니다. 게이트는 구성 가능한 임계값(validation.yaml의 spectral.gate.max_errors 및 spectral.gate.max_warnings)에 대해 오류 및 경고 수를 확인합니다.

6. 릴리스

scripts/release.py는 조정된 스펙을 버전이 지정된 ZIP 아카이브로 패키징합니다. 버전은 업스트림 스펙 메타데이터 날짜에서 파생된 YYYY.MM.DD-<patch> 형식을 사용합니다. 릴리스에는 다음이 포함됩니다:

개별 도메인 스펙 파일(268개 JSON 파일)
모든 도메인을 결합한 병합된 openapi.json
적용된 모든 수정 사항을 나열하는 CHANGELOG.md
VALIDATION_REPORT.md 요약

CI 작업은 ZIP이 첨부되고 v<version>으로 태그된 GitHub Release를 생성합니다. 콘텐츠 해시를 통해 변경 사항이 없을 때 중복 릴리스를 방지합니다.

문서 업데이트

병렬 CI 작업이 scripts/generate_docs.py를 사용하여 검증 리포트에서 docs/01-validation-report.mdx를 생성한 후, 내용이 변경되면 PR을 열게 됩니다.