Regole di Linting Spectral

Il progetto utilizza Spectral per il linting OAS3 con un’architettura a due configurazioni che separa il CI/gli strumenti esterni dalla logica personalizzata della pipeline.

Architettura a Due Configurazioni

.spectral.yaml — Configurazione Base

Utilizzata da GitHub Super-Linter e da qualsiasi strumento CI esterno. Estende spectral:oas (il set di regole OAS integrato). Non contiene funzioni personalizzate — questo la mantiene compatibile con gli strumenti che eseguono Spectral senza accesso alla directory spectral/functions/.

extends:
  - "spectral:oas"

rules:
  path-params: "off"
  operation-tags: warn
  oas3-api-servers: warn
  info-contact: warn
  oas3-unused-component: warn
  operation-operationId-unique: error
  oas3-valid-schema-example: error
  no-script-tags-in-markdown: warn
  operation-description: info
  info-description: info

spectral-pipeline.yaml — Configurazione della Pipeline

Utilizzata da scripts/spectral_lint.py (sia in modalità discover che gate). Estende la configurazione base e aggiunge la funzione personalizzata f5-path-params:

extends:
  - "./.spectral.yaml"

functionsDir: "./spectral/functions"
functions:
  - f5-path-params

rules:
  f5-path-params:
    description: "Path parameters must be declared and used"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: f5-path-params

Perché path-params È Disabilitata

La regola integrata path-params di Spectral segnala erroneamente le API F5 XC che utilizzano nomi di parametri con notazione a punti come {metadata.namespace} e {metadata.name}. La regola integrata non analizza i punti nei nomi dei parametri, quindi li segnala come non dichiarati.

La funzione personalizzata f5-path-params (spectral/functions/f5-path-params.js) gestisce correttamente i nomi con notazione a punti confrontando l’intero contenuto del {placeholder} con i nomi dei parametri dichiarati. Controlla sia i parametri a livello di percorso che a livello di operazione e segnala errori in entrambe le direzioni:

• Un placeholder nel percorso URL che non ha una corrispondente dichiarazione di parametro
• Un parametro di percorso dichiarato che non appare nel percorso URL

Riferimento delle Regole

Regole con Correzione Automatica

Queste regole vengono corrette automaticamente dal riconciliatore quando vengono rilevate violazioni. Consultare Correzioni Applicate per i dettagli su ciascuna correzione.

Regola	Severità	Metodo di Correzione	Descrizione
oas3-api-servers	warn	_add_servers	La specifica deve avere un blocco servers
info-contact	warn	_add_contact	info deve includere contact
operation-tags	warn	_add_tags	Ogni operazione deve avere almeno un tag
oas3-unused-component	warn	_remove_unused_component	Nessun schema di componente non referenziato
operation-operationId-unique	error	_deduplicate_operation_id	Tutti gli operationId devono essere univoci
oas3-valid-schema-example	error	_fix_schema_example	Esempi/valori predefiniti devono corrispondere al loro schema
no-script-tags-in-markdown	warn	_strip_script_tags	Nessun tag <script> nelle descrizioni
f5-path-params	error	—	I parametri di percorso devono essere dichiarati e utilizzati

Nota

f5-path-params è una regola con severità error ma non viene corretta automaticamente. Le violazioni indicano un difetto genuino della specifica che richiede una revisione manuale.

Regole Non Correggibili

Queste regole sono declassate a severità info perché non possono essere corrette automaticamente in modo significativo:

Regola	Severità	Descrizione
operation-description	info	Le operazioni dovrebbero avere una descrizione
info-description	info	Le informazioni dell’API dovrebbero avere una descrizione

Integrazione nella Pipeline

L’adattatore Spectral (scripts/spectral_lint.py) viene eseguito in due modalità:

Modalità Discover (Pre-Riconciliazione)

make spectral-lint
# Equivalent to: python -m scripts.spectral_lint --mode discover

Analizza specs/original/ e scrive reports/spectral_report.json. Il riconciliatore consuma questo report insieme al report di validazione.

Modalità Gate (Post-Riconciliazione)

make spectral-gate
# Equivalent to: python -m scripts.spectral_lint --mode gate

Analizza release/specs/ e scrive reports/spectral_gate_report.json. Restituisce il codice di uscita 1 se le violazioni superano le soglie configurate.

Mappatura delle Violazioni

Le violazioni Spectral vengono convertite in oggetti Discrepancy con tre sottotipi:

Categoria Regola Spectral	DiscrepancyType	Regole di Esempio
Elemento richiesto mancante	SPECTRAL_MISSING	oas3-api-servers, info-contact, operation-tags
Elemento esistente non valido	SPECTRAL_INVALID	oas3-valid-schema-example, no-script-tags-in-markdown
Codice morto	SPECTRAL_UNUSED	oas3-unused-component