Référence de configuration

Tout le comportement du pipeline est contrôlé par deux fichiers YAML dans config/.

config/validation.yaml

Paramètres de l’API

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

Champ	Description
base_url	URL de base de l’API de la console F5 XC. Peut être surchargée avec la variable d’environnement F5XC_API_URL.
tenant	Nom du tenant utilisé dans les chemins de l’API.
namespace	Espace de noms par défaut pour les opérations CRUD.
timeout	Délai d’expiration des requêtes HTTP en secondes.
retries	Nombre de tentatives de réessai en cas d’échec.
retry_delay	Secondes entre les réessais.

Attention

Les valeurs base_url, tenant et namespace dans validation.yaml sont des espaces réservés génériques. Vous devez les configurer pour votre environnement via des variables d’environnement avant d’exécuter le 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"

Les variables d’environnement prennent le pas sur les valeurs par défaut du YAML au moment de l’exécution.

Paramètres de téléchargement

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

Champ	Description
url	URL du bundle officiel de spécifications OpenAPI F5 XC (ZIP).
output_dir	Emplacement de stockage des spécifications extraites.
etag_cache	Fichier qui stocke l’ETag HTTP pour les téléchargements conditionnels.

Catégories de validation

Dix catégories correspondant aux types de contraintes du schéma OpenAPI. Chacune peut être activée/désactivée indépendamment.

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

Catégorie	Mots-clés
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

Paramètres Schemathesis

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

Champ	Description
enabled	Active ou désactive les tests Schemathesis.
max_examples	Nombre maximum de cas de test générés par opération.
hypothesis_phases	Phases Hypothesis à exécuter (generate, target).
stateful_testing	Active les tests à état basés sur les liens entre les opérations.
base_url_override	Surcharge l’URL de base de l’API pour les tests. null utilise api.base_url.
auth_header	Nom de l’en-tête HTTP pour l’authentification.
auth_prefix	Format du préfixe du jeton (les requêtes sont envoyées sous la forme APIToken <token>).

Paramètres de réconciliation

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

Champ	Description
priority	Ordre de préférence lorsque plusieurs sources de données sont en désaccord.
fix_strategies	Associe chaque type de divergence à son action corrective. Voir Corrections appliquées.

Paramètres 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>)"

Champ	Description
enabled	Active ou désactive entièrement le linting Spectral.
ruleset	Fichier de configuration Spectral à utiliser (le pipeline utilise spectral-pipeline.yaml).
auto_fix	Correspondance entre le nom de la règle et un booléen. true signifie que le réconciliateur corrigera les violations.
gate.max_errors	Nombre maximum d’erreurs autorisées dans la porte de validation post-réconciliation. null désactive la vérification.
gate.max_warnings	Nombre maximum d’avertissements. null désactive la vérification.
contact	Informations de contact injectées dans info.contact par le correcteur info-contact.
servers	Tableau de serveurs injecté par le correcteur oas3-api-servers.
security_scheme	Définition du schéma de sécurité injectée dans chaque spécification.

Paramètres des rapports

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

Paramètres de publication

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

Champ	Description
output_dir	Répertoire pour les artefacts de publication.
include_changelog	Inclut CHANGELOG.md dans le package de publication.
include_validation_report	Inclut le rapport de validation dans le package de publication.
version_from	Source de la version. git dérive la version à partir de la date des métadonnées de la spécification + numéro de correctif.

config/endpoints.yaml

Définit les points de terminaison de référence utilisés pour la validation en direct de l’API. Chaque entrée associe un nom de ressource logique à son fichier de spécification, son groupe d’API et ses chemins CRUD.

Structure d’un point de terminaison

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"

Champ	Description
resource	Nom de la ressource API (utilisé dans les chemins d’URL).
domain_file	Nom du fichier de spécification OpenAPI dans specs/original/.
api_group	Préfixe du groupe d’API (config, web, etc.).
crud_operations	Méthode HTTP et chemin pour chaque opération CRUD.
test_priority	high, medium ou low — contrôle l’ordre d’exécution des tests.
description	Description lisible de la ressource.

Points de terminaison de référence actuels

10 points de terminaison répartis sur trois domaines :

Point de terminaison	Domaine	Priorité
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

Ajout de nouveaux points de terminaison

Pour ajouter un nouveau point de terminaison à valider :

1. Trouvez le nom du fichier de spécification dans specs/original/ (format : docs-cloud-f5-com.NNNN.*.ves-swagger.json)
2. Ajoutez une entrée sous endpoints: en suivant la structure ci-dessus
3. Ajoutez la correspondance du fichier de domaine sous domain_files: avec un numéro de priorité
4. Ajoutez le nom du point de terminaison à test_order: à la position souhaitée

Astuce

Le framework valide l’ensemble des 268 spécifications pendant la réconciliation, indépendamment de ce qui est listé dans endpoints.yaml. La configuration des points de terminaison contrôle quelles ressources font l’objet de tests en direct de l’API avec Schemathesis.