Le rotture silenziose delle API continuano a piagare i sistemi distribuiti. Basta che uno sviluppatore rinomini un campo OpenAPI o rimuova un argomento da una query GraphQL per causare il crash a runtime dei servizi a valle. Le revisioni manuali delle pull request finiscono immancabilmente per trascurare lievi modifiche ai tipi o l'introduzione di nuovi campi obbligatori.
I limiti del diffing basato su testo
I classici git diff lavorano riga per riga e non hanno alcuna comprensione della semantica dei contratti API. Il semplice riordinamento delle chiavi, i cambi di formattazione o la riorganizzazione dello schema generano solo rumore visivo senza evidenziare le vere modifiche breaking. SpecDiff risolve il problema analizzando le specifiche OpenAPI 3.x e GraphQL tramite alberi sintattici astratti (AST), normalizzando le definizioni ed eseguendo comparazioni semantiche e strutturali.
Validazione programmatica degli schemi in Python
È possibile integrare SpecDiff direttamente nelle suite di test Python o negli script della pipeline CI. La libreria classifica le modifiche in aggiunte non-breaking, deprecazioni e violazioni critiche del contratto.
from specdiff import SchemaDiffer, SpecType
differ = SchemaDiffer(
old_spec="schemas/v1_openapi.json",
new_spec="schemas/v2_openapi.json",
spec_type=SpecType.OPENAPI,
strict_mode=True,
)
result = differ.compare()
if result.has_breaking_changes:
print(f"FAILED: Found {len(result.breaking_changes)} breaking changes.")
for change in result.breaking_changes:
print(f" - [{change.path}] {change.rule}: {change.message}")
exit(1)
print("SUCCESS: Schema changes are backward compatible.")Applicare la governance nel CI/CD moderno
Oltre a rilevare endpoint rimossi o variazioni di tipo, SpecDiff applica gli standard API aziendali. È possibile configurare regole per la documentazione mancante, definizioni di sicurezza errate o deprecazioni non approvate. Bloccando automaticamente le pull request non conformi, i team lead riducono il carico delle code review e proteggono la stabilità dell'infrastruttura.