配置参考

所有流水线行为由 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 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`	每个操作生成的最大测试用例数。
`hypothesis_phases`	要运行的 Hypothesis 阶段（`generate`、`target`）。
`stateful_testing`	启用跨操作的有状态链接测试。
`base_url_override`	覆盖测试的 API 基础 URL。`null` 使用 `api.base_url`。
`auth_header`	用于身份验证的 HTTP 头名称。
`auth_prefix`	令牌前缀格式（请求以 `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`	完全开启/关闭 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`	虚拟	high
`origin_pool`	虚拟	high
`app_firewall`	虚拟	high
`service_policy`	虚拟	medium
`api_definition`	API 安全	high
`api_discovery`	API 安全	medium
`api_groups`	API 安全	medium
`code_base_integration`	API 安全	low
`data_type`	数据隐私	medium
`sensitive_data_policy`	数据隐私	medium

添加新端点

要添加新的验证端点：

在 specs/original/ 中找到规范文件名（格式：docs-cloud-f5-com.NNNN.*.ves-swagger.json）
按照上述结构在 endpoints: 下添加一个条目
在 domain_files: 下添加域文件映射及优先级编号
将端点名称添加到 test_order: 中的期望位置