Correzioni applicate alle specifiche upstream

Il riconciliatore (scripts/reconcile.py) applica quattro categorie di correzioni alle specifiche upstream. Le correzioni dei vincoli modificano i contratti API per allinearli al comportamento osservato. Tutte le altre correzioni riguardano esclusivamente i metadati e non alterano i contratti API.

Correzioni dei vincoli

Queste correzioni regolano i vincoli degli schemi OpenAPI affinché la specifica corrisponda a ciò che l’API live effettivamente applica. Ogni correzione è guidata da un oggetto Discrepancy prodotto durante la validazione.

Strategia	Trigger	Cosa fa	Modifica del contratto
Relax	SPEC_STRICTER	La specifica rifiuta valori che l’API accetta. Abbassa minLength/minimum, alza maxLength/maximum, aggiunge valori enum mancanti.	Sì — amplia i valori accettati
Tighten	SPEC_LOOSER	La specifica accetta valori che l’API rifiuta. Alza minLength/minimum, abbassa maxLength/maximum, limita gli enum ai valori osservati.	Sì — restringe i valori accettati
Add	MISSING_CONSTRAINT	L’API applica un vincolo non documentato nella specifica. Aggiunge il vincolo allo schema.	Sì — aggiunge un nuovo vincolo
Remove	EXTRA_CONSTRAINT	La specifica dichiara un vincolo che l’API ignora. Rimuove il vincolo dallo schema.	Sì — rimuove il vincolo

Attenzione

Le correzioni dei vincoli modificano il contratto API. Vengono applicate solo quando supportate da evidenze provenienti da Schemathesis o da test di validazione dei vincoli eseguiti contro l’API live.

Tipi di vincoli supportati

Le 10 categorie di vincoli OpenAPI testate e corrette:

• Lunghezza stringa — minLength, maxLength
• Pattern — pattern (regex)
• Limiti numerici — minimum, maximum, exclusiveMinimum, exclusiveMaximum
• Campi obbligatori — required
• Valori enum — enum
• Limiti degli array — minItems, maxItems, uniqueItems
• Struttura degli oggetti — additionalProperties, properties, propertyNames
• Composizione — oneOf, anyOf, allOf
• Dipendenze — dependentRequired, dependentSchemas
• Tipi di dati — type, format

Arricchimenti Spectral

Queste correzioni risolvono problemi di qualità OAS3 individuati dal linting Spectral. Aggiungono o correggono metadati senza modificare il comportamento dell’API.

Iniezione del blocco servers

Regola: oas3-api-servers | Modifica del contratto: No

Aggiunge il template dell’URL del tenant F5 XC alle specifiche prive di un blocco 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"
    }
  }
}]

L’URL del server e i valori delle variabili provengono da spectral.servers in validation.yaml.

Iniezione delle informazioni di contatto

Regola: info-contact | Modifica del contratto: No

Aggiunge le informazioni di contatto in info.contact per le specifiche che ne sono prive:

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

I valori provengono da spectral.contact in validation.yaml.

Derivazione dei tag delle operazioni

Regola: operation-tags | Modifica del contratto: No

Deriva un tag dal prefisso del percorso URL per le operazioni prive di tag. Per un percorso come /api/config/namespaces/{namespace}/healthchecks, il tag è config (il secondo segmento non parametrico). Il tag viene aggiunto sia all’array tags dell’operazione sia alla lista tags a livello di specifica.

Rimozione dei componenti inutilizzati

Regola: oas3-unused-component | Modifica del contratto: No

Rimuove gli schemi dei componenti da components.schemas che non sono referenziati in nessun punto della specifica. Riduce la dimensione della specifica senza influire su alcuna operazione.

Deduplicazione degli operationId

Regola: operation-operationId-unique | Modifica del contratto: No

Aggiunge il metodo HTTP come suffisso (ad es. ListItems_get) quando più operazioni condividono lo stesso operationId. Questo rende ogni operationId univoco per i generatori di codice.

Rimozione di esempio/default non validi

Regola: oas3-valid-schema-example | Modifica del contratto: No

Rimuove i valori example o default dagli schemi quando il valore non è conforme ai vincoli dello schema stesso (tipo errato, fuori intervallo, ecc.). Impedisce ai generatori di codice di produrre payload di esempio non validi.

Rimozione dei tag script

Regola: no-script-tags-in-markdown | Modifica del contratto: No

Rimuove i tag <script> dai campi description tramite sostituzione regex. Alcune specifiche upstream contengono tag script iniettati che compromettono il funzionamento dei renderer della documentazione.

Metadati di sicurezza

Modifica del contratto: No (solo documentazione)

Ogni specifica riceve uno schema di sicurezza apiKeyAuth se non ne è già presente uno. Questo viene sempre iniettato indipendentemente dal fatto che Spectral lo abbia segnalato.

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

La definizione dello schema proviene da spectral.security_scheme in validation.yaml. Questo indica ai consumatori dell’API come autenticarsi, ma non modifica il comportamento a runtime.

Formattazione JSON

Modifica del contratto: No

Tutte le specifiche JSON in output passano attraverso un compattatore di array compatibile con Biome (_compact_short_arrays in scripts/utils/spec_loader.py). Gli array brevi che rientrano in 120 caratteri vengono compressi su una singola riga:

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

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

Gli array che superano la soglia di lunghezza della riga rimangono su più righe.

Priorità delle correzioni

Quando più strategie di correzione potrebbero essere applicabili, il riconciliatore utilizza un ordine di priorità configurato in reconciliation.priority:

1. existing — Usa il vincolo della specifica esistente se è valido
2. discovery — Usa il comportamento scoperto dall’API live
3. inferred — Inferisci da pattern riscontrati in endpoint simili

Ogni specifica corretta viene validata con openapi-spec-validator dopo l’applicazione di tutte le correzioni. Se la validazione fallisce, la specifica originale viene utilizzata come fallback e la correzione viene registrata come errore.