Guía de Desarrollo

Configuración

# Clonar e instalar dependencias de desarrollo
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Instalar Spectral CLI (requerido para las etapas de linting)
npm install -g @stoplight/spectral-cli

make dev-install crea un virtualenv en .venv/ e instala el proyecto con extras de desarrollo (pytest, ruff, mypy).

Variables de Entorno

La validación en vivo de la API requiere:

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

Sin estas variables, make validate recurre al modo de ejecución en seco (dry-run).

Ejecución del Pipeline

Pipeline Completo

make all
# Ejecuta: download → validate → spectral-lint → reconcile → spectral-gate → release

Etapas Individuales

make download        # Obtener specs del origen
make validate        # Ejecutar pruebas en vivo de la API (requiere token de API)
make validate-dry    # Ejecución en seco (sin llamadas a la API)
make spectral-lint   # Modo de descubrimiento de Spectral sobre specs originales
make reconcile       # Aplicar correcciones de ambos informes
make spectral-gate   # Puerta de calidad de Spectral sobre specs reconciliadas
make release         # Construir paquete de lanzamiento

Documentación

make docs-generate   # Regenerar docs/01-validation-report.mdx desde informes
make docs            # Construir sitio de documentación completo
make docs-serve      # Servidor de desarrollo local con recarga en caliente

Ejecución de Pruebas

make test           # pytest con cobertura
make lint           # ruff check + verificación de formato
make typecheck      # Verificación de tipos con mypy
make ci-test        # Los tres (usado en CI)

Los hooks de pre-commit se ejecutan automáticamente al hacer commit si están instalados:

make pre-commit-install   # Instalar hooks de git
make pre-commit           # Ejecutar todos los hooks manualmente

Estructura del Proyecto

scripts/
  download.py           # Etapa 1: Obtener specs de F5
  validate.py           # Etapa 2: Pruebas en vivo de la API
  spectral_lint.py      # Etapa 3/5: Adaptador de linting de Spectral
  reconcile.py          # Etapa 4: Aplicar correcciones a specs
  release.py            # Etapa 6: Empaquetar lanzamiento
  generate_docs.py      # Generar MDX desde informes
  utils/
    auth.py             # Autenticación de API F5 XC
    constraint_validator.py  # Pruebas de restricciones + tipos de Discrepancia
    report_generator.py      # Formato de informes
    schemathesis_runner.py   # Orquestación de pruebas Schemathesis
    spec_loader.py           # E/S de Specs + formato JSON

config/
  validation.yaml       # Configuración del pipeline
  endpoints.yaml        # Endpoints base para pruebas en vivo

spectral/
  functions/
    f5-path-params.js   # Función personalizada de Spectral

docs/                   # Documentación MDX de Starlight
tests/                  # Suite de pruebas pytest
release/specs/          # Salida: archivos de specs reconciliadas
reports/                # Salida: informes de validación y Spectral

Agregar un Nuevo Método de Corrección

Para agregar una nueva corrección automática de Spectral al reconciliador:

Agregar la regla a .spectral.yaml con la severidad deseada.
Habilitar la corrección automática en config/validation.yaml bajo spectral.auto_fix:
```
spectral:
  auto_fix:
    your-new-rule: true
```

Agregar el método de corrección a SpecReconciler en 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

Registrarlo en el despachador _apply_spectral_fix:

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

Agregar pruebas que cubran el nuevo método de corrección.

Agregar una Nueva Regla de Spectral

Para agregar una regla personalizada de Spectral con una función JavaScript:

Crear la función en spectral/functions/your-rule.js. Exportar una función por defecto que reciba (targetVal, options, context) y devuelva un arreglo de objetos {message, path}.

Registrarla en 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 de CI

El flujo de trabajo de GitHub Actions (validate-and-release.yml) se ejecuta en:

Programación: Diariamente a las 6 AM UTC
Push a main: Cuando cambian scripts/, config/ o pyproject.toml
Despacho manual: Con opciones para lanzamiento forzado o ejecución en seco

El flujo de trabajo tiene cuatro jobs:

validate — Descarga specs, ejecuta validación, lint de Spectral, reconciliación, puerta de Spectral
check-release-needed — Compara hashes de contenido para decidir si un lanzamiento es necesario
release — Empaqueta y crea un GitHub Release (solo si el contenido cambió)
update-docs — Regenera 01-validation-report.mdx y abre un PR si hubo cambios

Un job notify crea un issue en GitHub si algún job falla.

Flujo de Trabajo de Ramas y PR

Todos los cambios siguen: Issue -> Rama -> PR -> CI pasa -> Merge.

Nombres de ramas: feature/<issue>-desc, fix/<issue>-desc, docs/<issue>-desc
Los PRs deben vincular un issue (Closes #N en la descripción)
Verificaciones de CI requeridas: Check linked issues y Lint Code Base
Se prefiere squash merge; las ramas se eliminan automáticamente después del merge

Consulte CONTRIBUTING.md para las reglas completas del flujo de trabajo.