Guía de desarrollo

Esta guía describe el flujo de trabajo de desarrollo para el pipeline de enriquecimiento de la API de F5 XC.

Inicio rápido

Configuración inicial

# Clone the repository
git clone https://github.com/f5-sales-demo/api-specs-enriched.git
cd api-specs-enriched

# Create virtual environment and install dependencies
make install

# Install pre-commit hooks
make pre-commit-install

# Download specs and run pipeline
make build

# Preview documentation locally
make serve

Desarrollo diario

# Quick rebuild (uses cached specs)
make rebuild

# Run all quality checks
make pre-commit-run

# Preview documentation
make serve

Descripción general de la arquitectura

Diseño de dos carpetas

┌─────────────────────┐     ┌─────────────────────────────┐
│   specs/original/   │────▶│   docs/specifications/api/  │
│   (READ-ONLY)       │     │   (GENERATED)               │
│   - Downloaded      │     │   - Domain specs            │
│   - Gitignored      │     │   - Master spec             │
│   - ETag cached     │     │   - GitHub Pages            │
└─────────────────────┘     └─────────────────────────────┘

Flujo del pipeline

Download (ETag) → Enrich → Normalize → Merge → Lint → Serve
     │              │          │         │       │
     ▼              ▼          ▼         ▼       ▼
 270 specs     Branding    Fix refs   23 domains  Spectral
             + Grammar    + Types    + Master     rules

Estructura de directorios

Directorio	Propósito	Estado en Git
specs/original/	Especificaciones fuente de F5	Ignorado por Git
specs/discovered/	Salida de descubrimiento de API	Rastreado (openapi.json, session.json)
docs/specifications/api/	Especificaciones de dominio generadas	Ignorado por Git
scripts/	Scripts Python del pipeline	Rastreado
config/	Configuración del pipeline	Rastreado
reports/	Informes generados	Ignorado por Git

Patrones de flujo de trabajo

1. Flujo de trabajo de descubrimiento

Requisitos previos:

• Conexión VPN al entorno F5 XC
• Credenciales de API válidas

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

# Run discovery
make discover

# View results
jq '.statistics' specs/discovered/session.json

# Commit for CI/CD
make push-discovery

El descubrimiento captura:

• Campos requeridos/opcionales reales
• Valores de enumeración de respuestas en vivo
• Valores predeterminados
• Validaciones de patrones
• Ejemplos de respuesta

2. Flujo de trabajo de lanzamiento

Los lanzamientos son automatizados:

1. La programación diaria (6 AM UTC) o un push a la rama principal activa el flujo de trabajo
2. La verificación de ETag determina si las especificaciones de F5 han cambiado
3. El pipeline procesa y enriquece las especificaciones
4. La versión se calcula a partir de las etiquetas de git: git describe --tags --abbrev=0
5. Se crea un commit directo + etiqueta (sin PR de incremento de versión)
6. Se crea una versión de GitHub con el registro de cambios
7. La documentación se despliega en GitHub Pages

Reglas de incremento de versión:

Condición	Tipo de incremento	Ejemplo
[major] en el commit	Mayor	1.0.0 → 2.0.0
BREAKING CHANGE en el commit	Mayor	1.0.0 → 2.0.0
Nueva especificación de dominio agregada	Menor	1.0.0 → 1.1.0
Cualquier otro cambio	Parche	1.0.0 → 1.0.1

3. Flujo de trabajo de desarrollo

# Create feature branch
git checkout -b feature/my-change

# Make changes to config or scripts

# Test locally
make pipeline
make lint

# Commit (pre-commit hooks run automatically)
git add .
git commit -m "feat: add new enrichment rule"

# Push and create PR
git push -u origin feature/my-change
gh pr create

Análisis detallado del descubrimiento

¿Qué es el descubrimiento?

El descubrimiento explora la API de F5 XC en vivo para encontrar:

• Restricciones no documentadas: Campos requeridos no marcados en OpenAPI
• Valores de enumeración reales: Valores reales observados en producción
• Comportamientos predeterminados: Valores aplicados por el servidor cuando se omiten campos
• Patrones de respuesta: Formas de datos reales

Configuración del descubrimiento

config/discovery.yaml

discovery:
  exploration:
    namespaces:
      - "system"
      - "shared"
    methods:
      - "GET"
      - "OPTIONS"
    max_endpoints_per_run: 500

  schema_inference:
    sample_size: 3
    detect_patterns: true
    detect_constraints: true

Extensiones de descubrimiento

El descubrimiento agrega extensiones x-discovered-* a las especificaciones:

{
  "properties": {
    "name": {
      "type": "string",
      "x-discovered-required": true,
      "x-discovered-pattern": "^[a-z][a-z0-9-]*$",
      "x-discovered-examples": ["my-app", "prod-lb"]
    }
  }
}

Informe de análisis de restricciones

reports/constraint-analysis.md

make constraint-report

Proceso de lanzamiento

Contenido del paquete de lanzamiento

f5xc-api-specs-v1.0.14.zip
├── openapi.json       # Master combined spec
├── openapi.yaml       # YAML format
├── domains/           # Individual domain specs
│   ├── api_security.json
│   ├── load_balancer.json
│   └── ...
├── index.json         # Metadata
├── CHANGELOG.md       # Release notes
└── README.md          # Usage instructions

Activación manual del flujo de trabajo

gh workflow run sync-and-enrich.yml
gh run watch

Guía de configuración

Configuración de enriquecimiento

config/enrichment.yaml

enrichment:
  branding:
    replacements:
      "Volterra": "F5 Distributed Cloud"
      "VES": "F5 XC"

  acronyms:
    API: "Application Programming Interface"
    DNS: "Domain Name System"

  grammar:
    enabled: true
    language_tool: true

Configuración de normalización

config/normalization.yaml

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

Reglas de linting Spectral

config/spectral.yaml

extends:
  - spectral:oas

rules:
  operation-operationId: error
  operation-tags: warn

Extensiones de OpenAPI

El pipeline de enriquecimiento utiliza extensiones de proveedor para incorporar metadatos de validación y valores predeterminados.

Categorías de extensiones

Extensión	Significado	Implicación
x-f5xc-server-default	El servidor de la API de F5 XC aplica este valor cuando se omite el campo	El campo es opcional; omitirlo produce el comportamiento predeterminado documentado
x-f5xc-recommended-value	La consola web de F5 XC precompleta este valor para nuevos recursos	El campo no tiene un valor predeterminado del servidor, pero este valor representa la configuración típica
x-f5xc-recommended-oneof-variant	La F5 XC Consola preselecciona esta variante OneOf	Identifica la elección típica cuando existen múltiples opciones mutuamente excluyentes
x-f5xc-conflicts-with	Lista otras propiedades que no pueden usarse junto con este campo	La propiedad es parte de un grupo OneOf; solo una de las propiedades en conflicto puede especificarse

Extensiones de campo requerido

Extensión	Origen	Propósito
x-ves-required: "true"	Especificación original de F5 XC	El campo requiere un valor no nulo/no vacío
x-f5xc-required-for	Pipeline de enriquecimiento	Estado requerido específico según el contexto

Contextos de x-f5xc-required-for:

• create: Requerido al crear el recurso
• update: Requerido al actualizar el recurso
• minimum_config: Requerido para la configuración mínima viable

Extensiones de valor predeterminado y OneOf

Extensión	Propósito
x-f5xc-server-default: true	Marca los valores predeterminados aplicados por el servidor
x-f5xc-recommended-value	Valor precompleto por la consola de F5 XC
x-f5xc-recommended-oneof-variant	Variante OneOf recomendada
x-f5xc-conflicts-with	Exclusividad mutua con otras propiedades OneOf

x-f5xc-server-default

Tipo: boolean

Cuando es true, indica que el valor default que lo acompaña es aplicado por el servidor de la API de F5 XC. Los campos con esta extensión pueden omitirse de forma segura en las solicitudes de API: el servidor aplica el valor predeterminado automáticamente.

use_http2:
  type: boolean
  default: false
  x-f5xc-server-default: true

x-f5xc-recommended-value

Tipo: any (coincide con el tipo del campo)

Especifica un valor que la consola web de F5 XC utiliza como valor predeterminado precompleto. Este valor no es aplicado por el servidor, pero representa la configuración de inicio típica para nuevos recursos creados a través de la consola.

timeout:
  type: integer
  x-f5xc-recommended-value: 3

x-f5xc-recommended-oneof-variant

Tipo: object (mapa de nombre de grupo a nombre de variante)

Para esquemas con grupos de campos mutuamente excluyentes, identifica qué variante es la elección predeterminada o más común. La clave es el nombre del grupo OneOf y el valor es el nombre del campo de la variante recomendada.

healthcheckCreateSpecType:
  type: object
  x-f5xc-recommended-oneof-variant:
    health_check: "http_health_check"

x-f5xc-conflicts-with

Tipo: array de cadenas

Agregado en: v3.2.0 (Incidencia #494)

Declara relaciones de exclusividad mutua entre los miembros de un grupo OneOf. Se deriva automáticamente de las extensiones x-ves-oneof-field-*. Esto permite que las herramientas downstream (Terraform, CLI, MCP) validen los conflictos a nivel de esquema en lugar de en tiempo de ejecución.

host_header:
  type: string
  x-f5xc-conflicts-with: ["use_origin_server_name"]

use_origin_server_name:
  type: object
  x-f5xc-conflicts-with: ["host_header"]

Casos de uso:

• Los proveedores de Terraform pueden generar reglas de validación
• Las herramientas de CLI pueden advertir sobre combinaciones de campos en conflicto
• Los asistentes de IA pueden generar configuraciones OneOf correctas
• Las extensiones de IDE pueden proporcionar autocompletado consciente de conflictos

Origen: Derivado automáticamente de las extensiones nativas de F5 x-ves-oneof-field-* durante el enriquecimiento del pipeline.

Implicaciones de las reglas de validación

El enriquecedor inspecciona x-ves-validation-rules para inferir el estado requerido:

Regla	Implicación
ves.io.schema.rules.message.required: "true"	El campo es requerido
ves.io.schema.rules.uint32.gte: N	Si N >= 1 y no hay valor predeterminado del servidor, el campo es requerido
ves.io.schema.rules.repeated.min_items: N	Si N >= 1, el array requiere al menos N elementos
ves.io.schema.rules.string.min_bytes: N	Si N >= 1, la cadena requiere al menos N bytes

Recursos con valores predeterminados aplicados por el servidor

Algunos recursos aceptan especificaciones vacías porque el servidor aplica valores predeterminados:

Recurso	Valores predeterminados aplicados por el servidor
app_firewall	monitoring: \{\}, default_detection_settings: \{\}
rate_limiter	limits: [], user_identification: []
api_definition	swagger_specs: [], api_groups predeterminado
healthcheck	jitter: 0, jitter_percent: 0, valores predeterminados de http_health_check anidados

Para estos recursos, x-f5xc-required-for.create puede ser false incluso cuando x-ves-required es true.

Patrones de valor predeterminado

Patrón	Tipo	Ejemplo
\{\}	Objeto vacío (selección de opción)	monitoring: \{\}
[]	Array vacío	expected_status_codes: []
0	Numérico	jitter: 0
""	Cadena	expected_response: ""
false	Booleano	use_http2: false

Agregar valores predeterminados descubiertos

1. Crear el recurso en F5 XC con una especificación mínima a través de la API
2. Leer el recurso de vuelta para ver los valores aplicados por el servidor
3. Documentar los valores predeterminados en config/discovered_defaults.yaml
4. Ejecutar el pipeline: make pipeline
5. Verificar con: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

Solución de problemas

Pre-commit tarda demasiado

El pipeline se ejecuta en cada commit para garantizar la consistencia. Para commits de trabajo en progreso:

git commit --no-verify -m "WIP: work in progress"
# Run before final commit: make pre-commit-run

El descubrimiento falla

# Check VPN
ping your-tenant.console.ves.volterra.io

# Check credentials
echo $F5XC_API_TOKEN | head -c 10

# Check API URL format
echo $F5XC_API_URL
# Format: https://tenant.console.ves.volterra.io/api

Errores de lint en especificaciones generadas

# Check lint report
cat reports/lint-report.json | jq '.errors'

Corrija los problemas en la configuración de enriquecimiento/normalización, no en los archivos de salida.

Sistema de versiones

La versión se deriva de las etiquetas de git (p. ej., v2.0.38), eliminando las condiciones de carrera que causaban conflictos de fusión en PRs concurrentes.

# Version is calculated dynamically from git tags
from scripts.utils.version_calculator import get_version_from_tags
version = get_version_from_tags()  # Returns "2.0.38"

Especificaciones faltantes después de clonar

Las especificaciones generadas están ignoradas por Git:

make build  # Downloads and generates everything

Archivo grande bloqueado

Agregue una exclusión a .pre-commit-config.yaml:

- id: check-added-large-files
  exclude: ^path/to/large/file\.json$

Referencia rápida

Objetivos de Make

Objetivo	Descripción
make build	Compilación completa (descarga + pipeline)
make rebuild	Recompilación rápida (omite la descarga)
make download	Descarga especificaciones (con caché ETag)
make download-force	Fuerza la descarga
make pipeline	Ejecuta el pipeline de enriquecimiento
make lint	Linting con Spectral
make serve	Servidor de documentación local
make discover	Descubrimiento de API (requiere VPN)
make push-discovery	Confirma los datos de descubrimiento
make clean	Elimina los archivos generados
make pre-commit-run	Ejecuta todas las verificaciones de calidad

Variables de entorno

Variable	Propósito
F5XC_API_URL	URL de la API del tenant de F5 XC
F5XC_API_TOKEN	Token de autenticación de la API

Archivos clave

Archivo	Propósito
.etag	Último ETag descargado
CHANGELOG.md	Registro de cambios generado automáticamente
config/enrichment.yaml	Reglas de enriquecimiento
config/normalization.yaml	Reglas de normalización
config/discovery.yaml	Configuración de descubrimiento
config/spectral.yaml	Reglas de linting
scripts/utils/version_calculator.py	Cálculo de versión basado en etiquetas

Nota: La versión se deriva de las etiquetas de git (p. ej., v2.0.38), no de un archivo .version.