Guide de développement

Configuration

# Cloner et installer les dépendances de développement
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Installer Spectral CLI (requis pour les étapes de linting)
npm install -g @stoplight/spectral-cli

make dev-install crée un environnement virtuel dans .venv/ et installe le projet avec les extras de développement (pytest, ruff, mypy).

Variables d’environnement

La validation en direct de l’API nécessite :

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

Sans ces variables, make validate bascule en mode dry-run.

Exécution du pipeline

Pipeline complet

make all
# Exécute : download → validate → spectral-lint → reconcile → spectral-gate → release

Étapes individuelles

make download        # Récupérer les spécifications en amont
make validate        # Exécuter les tests API en direct (nécessite un jeton API)
make validate-dry    # Exécution à blanc (aucun appel API)
make spectral-lint   # Mode découverte Spectral sur les spécifications originales
make reconcile       # Appliquer les correctifs issus des deux rapports
make spectral-gate   # Porte de qualité Spectral sur les spécifications réconciliées
make release         # Construire le paquet de release

Documentation

make docs-generate   # Régénérer docs/01-validation-report.mdx à partir des rapports
make docs            # Construire le site de documentation complet
make docs-serve      # Serveur de développement local avec rechargement à chaud

Exécution des tests

make test           # pytest avec couverture
make lint           # ruff check + vérification du formatage
make typecheck      # Vérification de types mypy
make ci-test        # Les trois combinés (utilisé en CI)

Les hooks pre-commit s’exécutent automatiquement lors du commit s’ils sont installés :

make pre-commit-install   # Installer les hooks git
make pre-commit           # Exécuter tous les hooks manuellement

Structure du projet

scripts/
  download.py           # Étape 1 : Récupérer les spécifications depuis F5
  validate.py           # Étape 2 : Tests API en direct
  spectral_lint.py      # Étape 3/5 : Adaptateur de linting Spectral
  reconcile.py          # Étape 4 : Appliquer les correctifs aux spécifications
  release.py            # Étape 6 : Empaquetage de la release
  generate_docs.py      # Générer le MDX à partir des rapports
  utils/
    auth.py             # Authentification API F5 XC
    constraint_validator.py  # Tests de contraintes + types de divergences
    report_generator.py      # Formatage des rapports
    schemathesis_runner.py   # Orchestration des tests Schemathesis
    spec_loader.py           # E/S des spécifications + formatage JSON

config/
  validation.yaml       # Configuration du pipeline
  endpoints.yaml        # Points de terminaison de référence pour les tests en direct

spectral/
  functions/
    f5-path-params.js   # Fonction Spectral personnalisée

docs/                   # Documentation MDX Starlight
tests/                  # Suite de tests pytest
release/specs/          # Sortie : fichiers de spécifications réconciliés
reports/                # Sortie : rapports de validation et Spectral

Ajout d’une nouvelle méthode de correction

Pour ajouter une nouvelle correction automatique Spectral au réconcilieur :

Ajoutez la règle dans .spectral.yaml avec la sévérité souhaitée.
Activez la correction automatique dans config/validation.yaml sous spectral.auto_fix :
```
spectral:
  auto_fix:
    your-new-rule: true
```

Ajoutez la méthode de correction à SpecReconciler dans scripts/reconcile.py :

def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
    """Fix description."""
    # Modify spec in place
    # Return spec if changed, None if no change needed
    return spec

Enregistrez-la dans le dispatcher _apply_spectral_fix :

spectral_fixers = {
    # ... existing fixers ...
    "spectral:your-new-rule": self._fix_your_rule,
}

Ajoutez des tests couvrant la nouvelle méthode de correction.

Ajout d’une nouvelle règle Spectral

Pour ajouter une règle Spectral personnalisée avec une fonction JavaScript :

Créez la fonction dans spectral/functions/your-rule.js. Exportez une fonction par défaut qui reçoit (targetVal, options, context) et retourne un tableau d’objets {message, path}.

Enregistrez-la dans 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

Pipeline CI

Le workflow GitHub Actions (validate-and-release.yml) s’exécute lors de :

Planification : Quotidiennement à 6h UTC
Push sur main : Lorsque scripts/, config/ ou pyproject.toml sont modifiés
Déclenchement manuel : Avec des options pour une release forcée ou une exécution à blanc

Le workflow comporte quatre jobs :

validate — Télécharge les spécifications, exécute la validation, le lint Spectral, la réconciliation, la porte de qualité Spectral
check-release-needed — Compare les hachages de contenu pour déterminer si une release est justifiée
release — Empaquète et crée une Release GitHub (uniquement si le contenu a changé)
update-docs — Régénère 01-validation-report.mdx et ouvre une PR si des modifications sont détectées

Un job notify crée une issue GitHub si un job échoue.

Workflow de branches et PR

Toutes les modifications suivent : Issue -> Branche -> PR -> CI réussie -> Merge.

Noms de branches : feature/<issue>-desc, fix/<issue>-desc, docs/<issue>-desc
Les PR doivent référencer une issue (Closes #N dans la description)
Vérifications CI requises : Check linked issues et Lint Code Base
Le squash merge est préféré ; les branches sont automatiquement supprimées après le merge

Consultez CONTRIBUTING.md pour les règles complètes du workflow.