개발 가이드

설정

# 클론 및 개발 의존성 설치
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Spectral CLI 설치 (린팅 단계에 필요)
npm install -g @stoplight/spectral-cli

make dev-install은 .venv/에 가상환경을 생성하고 개발 extras(pytest, ruff, mypy)와 함께 프로젝트를 설치합니다.

환경 변수

라이브 API 검증에는 다음이 필요합니다:

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

이 변수들이 없으면 make validate는 드라이런 모드로 대체됩니다.

파이프라인 실행

전체 파이프라인

make all
# 실행 순서: download → validate → spectral-lint → reconcile → spectral-gate → release

개별 단계

make download        # 업스트림 스펙 가져오기
make validate        # 라이브 API 테스트 실행 (API 토큰 필요)
make validate-dry    # 드라이런 (API 호출 없음)
make spectral-lint   # 원본 스펙에 대한 Spectral 탐색 모드
make reconcile       # 두 리포트의 수정 사항 적용
make spectral-gate   # 조정된 스펙에 대한 Spectral 품질 게이트
make release         # 릴리스 패키지 빌드

문서화

make docs-generate   # 리포트에서 docs/01-validation-report.mdx 재생성
make docs            # 전체 문서 사이트 빌드
make docs-serve      # 핫 리로드를 지원하는 로컬 개발 서버

테스트 실행

make test           # 커버리지 포함 pytest
make lint           # ruff 검사 + 포맷 검사
make typecheck      # mypy 타입 검사
make ci-test        # 위 세 가지 모두 (CI에서 사용)

프리커밋 훅은 설치되어 있으면 커밋 시 자동으로 실행됩니다:

make pre-commit-install   # git 훅 설치
make pre-commit           # 모든 훅 수동 실행

프로젝트 구조

scripts/
  download.py           # 1단계: F5에서 스펙 가져오기
  validate.py           # 2단계: 라이브 API 테스트
  spectral_lint.py      # 3/5단계: Spectral 린팅 어댑터
  reconcile.py          # 4단계: 스펙에 수정 사항 적용
  release.py            # 6단계: 릴리스 패키징
  generate_docs.py      # 리포트에서 MDX 생성
  utils/
    auth.py             # F5 XC API 인증
    constraint_validator.py  # 제약 조건 테스트 + 불일치 유형
    report_generator.py      # 리포트 포맷팅
    schemathesis_runner.py   # Schemathesis 테스트 오케스트레이션
    spec_loader.py           # 스펙 I/O + JSON 포맷팅

config/
  validation.yaml       # 파이프라인 설정
  endpoints.yaml        # 라이브 테스트용 기준 엔드포인트

spectral/
  functions/
    f5-path-params.js   # 커스텀 Spectral 함수

docs/                   # Starlight MDX 문서
tests/                  # pytest 테스트 스위트
release/specs/          # 출력: 조정된 스펙 파일
reports/                # 출력: 검증 및 Spectral 리포트

새로운 수정 메서드 추가

조정기에 새로운 Spectral 자동 수정을 추가하려면:

규칙 추가: .spectral.yaml에 원하는 심각도와 함께 규칙을 추가합니다.
자동 수정 활성화: config/validation.yaml의 spectral.auto_fix 아래에 설정합니다:
```
spectral:
  auto_fix:
    your-new-rule: true
```

수정 메서드 추가: scripts/reconcile.py의 SpecReconciler에 추가합니다:

def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
    """Fix description."""
    # 스펙을 직접 수정
    # 변경된 경우 spec 반환, 변경이 필요 없으면 None 반환
    return spec

등록: _apply_spectral_fix 디스패처에 등록합니다:

spectral_fixers = {
    # ... 기존 수정기 ...
    "spectral:your-new-rule": self._fix_your_rule,
}

테스트 추가: 새로운 수정 메서드를 커버하는 테스트를 추가합니다.

새로운 Spectral 규칙 추가

JavaScript 함수를 사용하는 커스텀 Spectral 규칙을 추가하려면:

spectral/functions/your-rule.js에 함수를 생성합니다. (targetVal, options, context)를 받아 {message, path} 객체 배열을 반환하는 기본 함수를 내보냅니다.

spectral-pipeline.yaml에 등록합니다:

functions:
  - f5-path-params
  - your-rule

rules:
  your-rule:
    description: "What it checks"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: your-rule

CI 파이프라인

GitHub Actions 워크플로우(validate-and-release.yml)는 다음 조건에서 실행됩니다:

스케줄: 매일 UTC 오전 6시
main으로 푸시: scripts/, config/, 또는 pyproject.toml이 변경된 경우
수동 디스패치: 강제 릴리스 또는 드라이런 옵션 포함

워크플로우는 네 개의 작업으로 구성됩니다:

validate — 스펙 다운로드, 검증 실행, Spectral 린트, 조정, Spectral 게이트
check-release-needed — 콘텐츠 해시를 비교하여 릴리스 필요 여부 결정
release — 패키징 및 GitHub 릴리스 생성 (콘텐츠가 변경된 경우에만)
update-docs — 01-validation-report.mdx를 재생성하고 변경된 경우 PR 생성

notify 작업은 어떤 작업이든 실패하면 GitHub 이슈를 생성합니다.

브랜치 및 PR 워크플로우

모든 변경 사항은 다음을 따릅니다: 이슈 -> 브랜치 -> PR -> CI 통과 -> 머지.

브랜치 이름: feature/<issue>-desc, fix/<issue>-desc, docs/<issue>-desc
PR은 이슈를 연결해야 합니다 (설명에 Closes #N 포함)
필수 CI 검사: Check linked issues 및 Lint Code Base
스쿼시 머지 권장; 머지 후 브랜치 자동 삭제

전체 워크플로우 규칙은 CONTRIBUTING.md를 참조하십시오.