설정 참조

모든 파이프라인 동작은 config/ 디렉토리의 두 YAML 파일로 제어됩니다.

`config/validation.yaml`

API 설정

api:
  base_url: "https://example-tenant.console.ves.volterra.io"
  tenant: "example-tenant"
  namespace: "example-namespace"
  timeout: 30
  retries: 3
  retry_delay: 2

필드	설명
`base_url`	F5 XC 콘솔 API 기본 URL. `F5XC_API_URL` 환경 변수로 재정의할 수 있습니다.
`tenant`	API 경로에 사용되는 테넌트 이름.
`namespace`	CRUD 작업의 기본 네임스페이스.
`timeout`	HTTP 요청 타임아웃(초).
`retries`	실패 시 재시도 횟수.
`retry_delay`	재시도 간격(초).

validation.yaml의 base_url, tenant, namespace 값은 일반적인 플레이스홀더입니다. 파이프라인을 실행하기 전에 환경 변수를 통해 해당 환경에 맞게 반드시 설정해야 합니다:

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

환경 변수는 런타임에 YAML 기본값보다 우선합니다.

다운로드 설정

download:
  url: "https://docs.cloud.f5.com/docs-v2/downloads/f5-distributed-cloud-open-api.zip"
  output_dir: "specs/original"
  etag_cache: ".etag_cache"

필드	설명
`url`	공식 F5 XC OpenAPI 스펙 번들(ZIP)의 URL.
`output_dir`	추출된 스펙이 저장되는 위치.
`etag_cache`	조건부 다운로드를 위한 HTTP ETag를 저장하는 파일.

유효성 검사 카테고리

OpenAPI 스키마 제약 조건 유형에 해당하는 10개의 카테고리입니다. 각 카테고리는 독립적으로 활성화/비활성화할 수 있습니다.

validation_categories:
  string_length:
    enabled: true
    keywords: ["minLength", "maxLength"]
    description: "Validate string length boundaries"

카테고리	키워드
`string_length`	`minLength`, `maxLength`
`pattern`	`pattern`
`numeric_bounds`	`minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
`required_fields`	`required`
`enum_values`	`enum`
`array_bounds`	`minItems`, `maxItems`, `uniqueItems`
`object_structure`	`additionalProperties`, `properties`, `propertyNames`
`composition`	`oneOf`, `anyOf`, `allOf`
`dependencies`	`dependentRequired`, `dependentSchemas`
`data_types`	`type`, `format`

Schemathesis 설정

schemathesis:
  enabled: true
  max_examples: 100
  hypothesis_phases:
    - generate
    - target
  stateful_testing: true
  base_url_override: null
  auth_header: "Authorization"
  auth_prefix: "APIToken"

필드	설명
`enabled`	Schemathesis 테스트 토글.
`max_examples`	작업당 생성되는 최대 테스트 케이스 수.
`hypothesis_phases`	실행할 Hypothesis 단계 (`generate`, `target`).
`stateful_testing`	작업 간 상태 기반 링크 테스트 활성화.
`base_url_override`	테스트용 API 기본 URL 재정의. `null`이면 `api.base_url`을 사용합니다.
`auth_header`	인증에 사용되는 HTTP 헤더 이름.
`auth_prefix`	토큰 접두사 형식 (요청은 `APIToken <token>` 형태로 전송됩니다).

조정(Reconciliation) 설정

reconciliation:
  priority:
    - existing
    - discovery
    - inferred
  fix_strategies:
    tighter_spec: "relax"
    looser_spec: "tighten"
    missing_constraint: "add"
    extra_constraint: "remove"

필드	설명
`priority`	여러 데이터 소스가 일치하지 않을 때의 우선순위.
`fix_strategies`	각 불일치 유형을 수정 작업에 매핑합니다. 적용된 수정 사항을 참조하세요.

Spectral 설정

spectral:
  enabled: true
  ruleset: "spectral-pipeline.yaml"
  auto_fix:
    oas3-api-servers: true
    info-contact: true
    operation-tags: true
    oas3-unused-component: true
    operation-operationId-unique: true
    oas3-valid-schema-example: true
    no-script-tags-in-markdown: true
  gate:
    max_errors: null
    max_warnings: null
  contact:
    name: "F5 Distributed Cloud"
    url: "https://docs.cloud.f5.com"
    email: "support@f5.com"
  servers:
    - url: "https://{tenant}.console.ves.volterra.io"
      description: "F5 Distributed Cloud API"
      variables:
        tenant:
          default: "example-tenant"
          description: "Your F5 XC tenant name"
  security_scheme:
    type: "apiKey"
    in: "header"
    name: "Authorization"
    description: "F5 XC API Token (format: APIToken <token>)"

필드	설명
`enabled`	Spectral 린팅 전체 토글.
`ruleset`	사용할 Spectral 설정 파일 (파이프라인은 `spectral-pipeline.yaml`을 사용합니다).
`auto_fix`	규칙 이름과 불리언 값의 매핑. `true`이면 조정기가 위반 사항을 수정합니다.
`gate.max_errors`	조정 후 게이트에서 허용되는 최대 오류 수. `null`이면 검사를 비활성화합니다.
`gate.max_warnings`	허용되는 최대 경고 수. `null`이면 검사를 비활성화합니다.
`contact`	`info-contact` 수정기가 `info.contact`에 삽입하는 연락처 정보.
`servers`	`oas3-api-servers` 수정기가 삽입하는 서버 배열.
`security_scheme`	모든 스펙에 삽입되는 보안 스키마 정의.

보고서 설정

reports:
  output_dir: "reports"
  formats:
    - json
    - html
    - markdown
  include_examples: true
  max_examples_per_issue: 5

릴리스 설정

release:
  output_dir: "release"
  include_changelog: true
  include_validation_report: true
  version_from: "git"

필드	설명
`output_dir`	릴리스 아티팩트 디렉토리.
`include_changelog`	릴리스 패키지에 `CHANGELOG.md`를 포함합니다.
`include_validation_report`	릴리스 패키지에 유효성 검사 보고서를 포함합니다.
`version_from`	버전 소스. `git`은 스펙 메타데이터 날짜 + 패치 번호에서 버전을 도출합니다.

`config/endpoints.yaml`

라이브 API 유효성 검사에 사용되는 기준 엔드포인트를 정의합니다. 각 항목은 논리적 리소스 이름을 스펙 파일, API 그룹 및 CRUD 경로에 매핑합니다.

엔드포인트 구조

endpoints:
  healthcheck:
    resource: healthchecks
    domain_file: docs-cloud-f5-com.0124.public.ves.io.schema.healthcheck.ves-swagger.json
    api_group: config
    crud_operations:
      create: POST /api/config/namespaces/{namespace}/healthchecks
      read: GET /api/config/namespaces/{namespace}/healthchecks/{name}
      list: GET /api/config/namespaces/{namespace}/healthchecks
      update: PUT /api/config/namespaces/{namespace}/healthchecks/{name}
      delete: DELETE /api/config/namespaces/{namespace}/healthchecks/{name}
    test_priority: high
    description: "Health check configurations for origin monitoring"

필드	설명
`resource`	API 리소스 이름 (URL 경로에 사용됨).
`domain_file`	`specs/original/`에 있는 OpenAPI 스펙의 파일명.
`api_group`	API 그룹 접두사 (`config`, `web` 등).
`crud_operations`	각 CRUD 작업에 대한 HTTP 메서드 및 경로.
`test_priority`	`high`, `medium` 또는 `low` — 테스트 실행 순서를 제어합니다.
`description`	리소스에 대한 사람이 읽을 수 있는 설명.

현재 기준 엔드포인트

세 가지 도메인에 걸쳐 10개의 엔드포인트:

엔드포인트	도메인	우선순위
`healthcheck`	Virtual	high
`origin_pool`	Virtual	high
`app_firewall`	Virtual	high
`service_policy`	Virtual	medium
`api_definition`	API Security	high
`api_discovery`	API Security	medium
`api_groups`	API Security	medium
`code_base_integration`	API Security	low
`data_type`	Data Privacy	medium
`sensitive_data_policy`	Data Privacy	medium

새 엔드포인트 추가

유효성 검사를 위한 새 엔드포인트를 추가하려면:

specs/original/에서 스펙 파일명을 찾습니다 (형식: docs-cloud-f5-com.NNNN.*.ves-swagger.json)
위의 구조를 따라 endpoints: 아래에 항목을 추가합니다
domain_files: 아래에 우선순위 번호와 함께 도메인 파일 매핑을 추가합니다
원하는 위치의 test_order:에 엔드포인트 이름을 추가합니다