Controllo dei campi obbligatori OpenAPI

Le quattro parti obbligatorie

Il valore di info.version è la versione della tua API, non quella della specifica OpenAPI. Spesso viene omesso perché la versione della specifica compare già in cima.

Un esempio pratico con tutto mancante

servers:
  - url: https://api.example.com

Questo documento minuscolo non contiene nessuna delle parti obbligatorie. Il report elenca tre errori:

Quando manca l’intero oggetto info, lo strumento segnala quell’unico errore e non elenca separatamente titolo e versione. Aggiungi info con entrambi i campi e la prossima esecuzione segnalerà quelli che mancano ancora.

Scheletro di partenza

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Questo scheletro supera tutti i controlli sui campi obbligatori. Sostituisci i nomi con i tuoi e costruisci a partire da qui. Risposte, schema e sicurezza non rientrano in questo controllo.

Quando eseguire questo controllo

Eseguilo quando inizi una spec da zero, dopo averla generata dal codice e prima di inviarla a chi la importerà in un altro strumento. Molti importatori si fermano al primo campo obbligatorio mancante con un messaggio breve, quindi individuarli tutti in un solo passaggio fa risparmiare parecchi giri. È anche un promemoria utile per chi inizia, che spesso dimentica info.version o lascia fuori paths mentre abbozza un’API.

Dopo che i campi obbligatori sono a posto, le aggiunte utili successive sono una breve description sotto info, una voce servers e un operationId su ogni operazione. Qui non vengono controllate, ma rendono la spec più leggibile e più facile da trasformare in codice client.