Correcciones Aplicadas a las Especificaciones Upstream

El reconciliador (scripts/reconcile.py) aplica cuatro categorías de correcciones a las especificaciones upstream. Las correcciones de restricciones modifican los contratos de API para coincidir con el comportamiento observado. Todas las demás correcciones son únicamente de metadatos y no alteran los contratos de API.

Correcciones de Restricciones

Estas correcciones ajustan las restricciones del esquema OpenAPI para que la especificación coincida con lo que la API en vivo realmente aplica. Cada corrección es impulsada por un objeto Discrepancy producido durante la validación.

Estrategia	Disparador	Qué Hace	Cambio de Contrato
Relajar	SPEC_STRICTER	La especificación rechaza valores que la API acepta. Reduce minLength/minimum, aumenta maxLength/maximum, agrega valores enum faltantes.	Sí — amplía los valores aceptados
Restringir	SPEC_LOOSER	La especificación acepta valores que la API rechaza. Aumenta minLength/minimum, reduce maxLength/maximum, restringe los enums a los valores observados.	Sí — reduce los valores aceptados
Agregar	MISSING_CONSTRAINT	La API aplica una restricción no documentada en la especificación. Agrega la restricción al esquema.	Sí — agrega nueva restricción
Eliminar	EXTRA_CONSTRAINT	La especificación declara una restricción que la API ignora. Elimina la restricción del esquema.	Sí — elimina restricción

Precaución

Las correcciones de restricciones modifican el contrato de API. Solo se aplican cuando están respaldadas por evidencia de Schemathesis o pruebas de validación de restricciones contra la API en vivo.

Tipos de Restricciones Soportados

Las 10 categorías de restricciones OpenAPI probadas y corregidas:

• Longitud de cadena — minLength, maxLength
• Patrón — pattern (regex)
• Límites numéricos — minimum, maximum, exclusiveMinimum, exclusiveMaximum
• Campos requeridos — required
• Valores enum — enum
• Límites de array — minItems, maxItems, uniqueItems
• Estructura de objeto — additionalProperties, properties, propertyNames
• Composición — oneOf, anyOf, allOf
• Dependencias — dependentRequired, dependentSchemas
• Tipos de datos — type, format

Enriquecimientos de Spectral

Estas correcciones abordan problemas de calidad OAS3 encontrados por el linting de Spectral. Agregan o corrigen metadatos sin cambiar el comportamiento de la API.

Inyección del Bloque Servers

Regla: oas3-api-servers | Cambio de contrato: No

Agrega la plantilla de URL del tenant de F5 XC a las especificaciones que carecen de un bloque servers:

"servers": [{
  "url": "https://{tenant}.console.ves.volterra.io",
  "description": "F5 Distributed Cloud API",
  "variables": {
    "tenant": {
      "default": "example-tenant",
      "description": "Your F5 XC tenant name"
    }
  }
}]

La URL del servidor y los valores de las variables provienen de spectral.servers en validation.yaml.

Inyección de Información de Contacto

Regla: info-contact | Cambio de contrato: No

Agrega información de contacto a info.contact para las especificaciones que carecen de ella:

"contact": {
  "name": "F5 Distributed Cloud",
  "url": "https://docs.cloud.f5.com",
  "email": "support@f5.com"
}

Los valores provienen de spectral.contact en validation.yaml.

Derivación de Tags de Operación

Regla: operation-tags | Cambio de contrato: No

Deriva un tag del prefijo de ruta URL para operaciones sin etiquetar. Para una ruta como /api/config/namespaces/{namespace}/healthchecks, el tag es config (el segundo segmento que no es parámetro). El tag se agrega tanto al array tags de la operación como a la lista tags a nivel de especificación.

Eliminación de Componentes No Utilizados

Regla: oas3-unused-component | Cambio de contrato: No

Elimina esquemas de componentes de components.schemas que no están referenciados en ningún lugar de la especificación. Reduce el tamaño de la especificación sin afectar ninguna operación.

Deduplicación de OperationId

Regla: operation-operationId-unique | Cambio de contrato: No

Agrega el método HTTP como sufijo (por ejemplo, ListItems_get) cuando múltiples operaciones comparten el mismo operationId. Esto hace que cada operationId sea único para los generadores de código.

Eliminación de Ejemplos/Valores por Defecto Inválidos

Regla: oas3-valid-schema-example | Cambio de contrato: No

Elimina valores example o default de los esquemas cuando el valor no cumple con las restricciones propias del esquema (tipo incorrecto, fuera de rango, etc.). Evita que los generadores de código produzcan payloads de ejemplo inválidos.

Eliminación de Tags Script

Regla: no-script-tags-in-markdown | Cambio de contrato: No

Elimina tags <script> de los campos description usando un reemplazo por regex. Algunas especificaciones upstream contienen tags script inyectados que rompen los renderizadores de documentación.

Metadatos de Seguridad

Cambio de contrato: No (solo documentación)

Cada especificación recibe un esquema de seguridad apiKeyAuth si no hay uno presente. Esto siempre se inyecta independientemente de si Spectral lo señaló.

"components": {
  "securitySchemes": {
    "apiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "F5 XC API Token (format: APIToken <token>)"
    }
  }
},
"security": [{ "apiKeyAuth": [] }]

La definición del esquema proviene de spectral.security_scheme en validation.yaml. Esto indica a los consumidores de la API cómo autenticarse pero no cambia el comportamiento en tiempo de ejecución.

Formato JSON

Cambio de contrato: No

Todas las especificaciones JSON de salida pasan por un compactador de arrays compatible con Biome (_compact_short_arrays en scripts/utils/spec_loader.py). Los arrays cortos que caben dentro de 120 caracteres se colapsan en una sola línea:

// Before
"enum": [
  "ACTIVE",
  "INACTIVE"
]

// After
"enum": ["ACTIVE", "INACTIVE"]

Los arrays que exceden el umbral de longitud de línea permanecen en múltiples líneas.

Prioridad de Correcciones

Cuando múltiples estrategias de corrección podrían aplicarse, el reconciliador usa un orden de prioridad configurado en reconciliation.priority:

1. existing — Usar la restricción existente de la especificación si es válida
2. discovery — Usar el comportamiento descubierto de la API en vivo
3. inferred — Inferir a partir de patrones en endpoints similares

Cada especificación corregida se valida con openapi-spec-validator después de aplicar todas las correcciones. Si la validación falla, se usa la especificación original como respaldo y la corrección se registra como un error.