เอกสารอ้างอิงการกำหนดค่า

พฤติกรรมทั้งหมดของ pipeline ถูกควบคุมโดยไฟล์ YAML สองไฟล์ใน config/

`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`	URL พื้นฐานของ API คอนโซล F5 XC สามารถแทนที่ด้วยตัวแปรสภาพแวดล้อม `F5XC_API_URL`
`tenant`	ชื่อ tenant ที่ใช้ในเส้นทาง API
`namespace`	namespace เริ่มต้นสำหรับการดำเนินการ CRUD
`timeout`	ระยะเวลาหมดเวลาของคำขอ HTTP เป็นวินาที
`retries`	จำนวนครั้งในการลองใหม่เมื่อเกิดความล้มเหลว
`retry_delay`	จำนวนวินาทีระหว่างการลองใหม่แต่ละครั้ง

ค่า base_url, tenant และ namespace ใน validation.yaml เป็นค่าตัวแทนทั่วไป คุณจำเป็นต้องกำหนดค่าเหล่านี้สำหรับสภาพแวดล้อมของคุณผ่านตัวแปรสภาพแวดล้อมก่อนรัน pipeline:

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`	URL ของชุด OpenAPI spec อย่างเป็นทางการของ F5 XC (ZIP)
`output_dir`	ตำแหน่งที่จัดเก็บ spec ที่แตกไฟล์แล้ว
`etag_cache`	ไฟล์ที่จัดเก็บ HTTP ETag สำหรับการดาวน์โหลดแบบมีเงื่อนไข

หมวดหมู่การตรวจสอบ

สิบหมวดหมู่ที่สอดคล้องกับประเภทข้อจำกัดของ OpenAPI schema แต่ละหมวดหมู่สามารถเปิด/ปิดใช้งานได้อย่างอิสระ

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`	จำนวนสูงสุดของกรณีทดสอบที่สร้างขึ้นต่อ operation
`hypothesis_phases`	เฟสของ Hypothesis ที่จะรัน (`generate`, `target`)
`stateful_testing`	เปิดใช้การทดสอบแบบ stateful ที่อิงตาม link ข้าม operation
`base_url_override`	แทนที่ URL พื้นฐานของ API สำหรับการทดสอบ `null` จะใช้ `api.base_url`
`auth_header`	ชื่อ HTTP header สำหรับการยืนยันตัวตน
`auth_prefix`	รูปแบบ prefix ของ token (คำขอจะถูกส่งเป็น `APIToken <token>`)

การตั้งค่าการปรับปรุงความสอดคล้อง

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`	เปิด/ปิดการ lint ด้วย Spectral ทั้งหมด
`ruleset`	ไฟล์กำหนดค่า Spectral ที่จะใช้ (pipeline ใช้ `spectral-pipeline.yaml`)
`auto_fix`	แมปชื่อกฎกับค่า boolean `true` หมายความว่า reconciler จะแก้ไขการละเมิดกฎ
`gate.max_errors`	จำนวน error สูงสุดที่อนุญาตใน gate หลังการปรับปรุง `null` จะปิดใช้งานการตรวจสอบ
`gate.max_warnings`	จำนวน warning สูงสุดที่อนุญาต `null` จะปิดใช้งานการตรวจสอบ
`contact`	ข้อมูลติดต่อที่ถูกใส่ลงใน `info.contact` โดย fixer `info-contact`
`servers`	อาร์เรย์ servers ที่ถูกใส่โดย fixer `oas3-api-servers`
`security_scheme`	คำจำกัดความ security scheme ที่ถูกใส่ลงในทุก spec

การตั้งค่ารายงาน

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`	ไดเรกทอรีสำหรับ artifact ของการเผยแพร่
`include_changelog`	รวม `CHANGELOG.md` ในแพ็คเกจเผยแพร่
`include_validation_report`	รวมรายงานการตรวจสอบในแพ็คเกจเผยแพร่
`version_from`	แหล่งที่มาของเวอร์ชัน `git` จะคำนวณเวอร์ชันจากวันที่ metadata ของ spec + หมายเลข patch

`config/endpoints.yaml`

กำหนด endpoint พื้นฐานที่ใช้สำหรับการตรวจสอบ API แบบ live แต่ละรายการแมปชื่อทรัพยากรเชิงตรรกะกับไฟล์ spec, กลุ่ม API และเส้นทาง CRUD

โครงสร้าง Endpoint

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`	ชื่อไฟล์ของ OpenAPI spec ใน `specs/original/`
`api_group`	prefix กลุ่ม API (`config`, `web` ฯลฯ)
`crud_operations`	HTTP method และเส้นทางสำหรับแต่ละการดำเนินการ CRUD
`test_priority`	`high`, `medium` หรือ `low` — ควบคุมลำดับการรันทดสอบ
`description`	คำอธิบายทรัพยากรที่มนุษย์อ่านได้

Endpoint พื้นฐานปัจจุบัน

10 endpoint ข้ามสามโดเมน:

Endpoint	โดเมน	ลำดับความสำคัญ
`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

การเพิ่ม Endpoint ใหม่

ในการเพิ่ม endpoint ใหม่สำหรับการตรวจสอบ:

ค้นหาชื่อไฟล์ spec ใน specs/original/ (รูปแบบ: docs-cloud-f5-com.NNNN.*.ves-swagger.json)
เพิ่มรายการภายใต้ endpoints: ตามโครงสร้างด้านบน
เพิ่มการแมปไฟล์โดเมนภายใต้ domain_files: พร้อมหมายเลขลำดับความสำคัญ
เพิ่มชื่อ endpoint ลงใน test_order: ในตำแหน่งที่ต้องการ