Controllo di qualità di un OpenAPI
OpenAPI Linter
Controlla in un documento OpenAPI le risposte mancanti, gli schemi inutilizzati, i riferimenti che non puntano a niente e gli altri difetti che rompono i generatori di codice.
Controlla un documento OpenAPI 3.0 o 3.1 cercando le cose che rompono i generatori di codice, che fanno mentire le librerie client o che la specifica semplicemente richiede. Le regole sono scritte a mano ed elencate nella pagina — problemi, non preferenze di stile.
Documento OpenAPI
Trascina qui un openapi.yaml
Letto solo in questa scheda.
24 rilievi
erroreschema-array-itemscomponents.schemas.Order.items
`type: array` senza `items`.
errorepath-param-undeclaredGET /orders/{orderId}
`{orderId}` nel percorso non è dichiarato come parametro.
erroreresponse-descriptionGET /orders/{orderId}
Alla risposta `200` manca la description.
erroreschema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` senza `items`.
erroreinfo-missinginfo
Non c’è `info.version`. È la versione dell’API, non quella di OpenAPI.
erroreoperation-id-duplicatePOST /orders/{orderId}
L’operationId `getOrder` c’è anche su GET /orders/{orderId}.
errorepath-param-requiredPOST /orders/{orderId}
Al parametro `in: path` `id` manca `required: true`.
errorepath-param-undeclaredPOST /orders/{orderId}
`{orderId}` nel percorso non è dichiarato come parametro.
errorepath-param-unusedPOST /orders/{orderId}
Il parametro `in: path` `id` non compare nel percorso.
avvisopath-trailing-slash/orders/
Questo percorso finisce con `/`.
avvisoschema-unusedcomponents.schemas.Customer
Niente referenzia questo schema.
avvisooperation-id-missingGET /orders/
Non c’è un operationId.
avvisoresponse-errorGET /orders/
Non c’è nessuna risposta 4xx.
avvisodescription-missingGET /orders/{orderId}
Non c’è né summary né description.
avvisoresponse-errorGET /orders/{orderId}
Non c’è nessuna risposta 4xx.
avvisodescription-missingPOST /orders/{orderId}
Non c’è né summary né description.
avvisoresponse-errorPOST /orders/{orderId}
Non c’è nessuna risposta 4xx.
avvisoresponse-successPOST /orders/{orderId}
Non c’è nessuna risposta 2xx o 3xx.
notatag-missingGET /orders/
Non c’è nessun tag.
notatag-missingGET /orders/{orderId}
Non c’è nessun tag.
notaparameter-descriptionPOST /orders/{orderId}
Al parametro `id` manca la description.
notaresponse-default-onlyPOST /orders/{orderId}
L’unica risposta è `default`.
notatag-missingPOST /orders/{orderId}
Non c’è nessun tag.
notaservers-missingservers
Non è elencato nessun server, quindi l’URL di base è `/`.
OpenAPI
3.0.3
Operazioni
3
Errori
9
Avvisi
9
Note
6
Un insieme di regole scritto a mano. Prende quello che fa inciampare un generatore di codice, quello che fa mentire una libreria client e quello che la specifica richiede davvero — problemi, non preferenze. Non carica i set di regole di Spectral.
Per vedere che cosa è cambiato fra due versioni, usa Confronto fra versioni OpenAPI.
Come si usa
Incollare il documento
JSON o YAML, 3.0 o 3.1. Viene analizzato in questa scheda; non viene caricato nulla.
Affrontare prima gli errori
Ogni segnalazione porta l’id della regola e il punto esatto nel documento. Gli errori sono cose che andranno davvero storte; gli avvisi sono cose che di solito ci andranno.
Leggere l’elenco delle regole quando una segnalazione sorprende
Ogni regola è scritta per esteso con la sua gravità e il motivo per cui esiste, così una segnalazione su cui non si è d’accordo è almeno un ragionamento che si può leggere.
Domande frequenti
Può caricare il mio ruleset di Spectral?
No. Questo è un insieme di regole fisso, scritto a mano, scelto per i problemi e non per lo stile della casa. Se si ha una configurazione Spectral, lo strumento che la rispetterà è Spectral.
Non legge il mio file Swagger 2.0.
Esatto: 2.0 è una forma di documento diversa, non un 3.0 un po’ più vecchio, e metà delle regole non vi si applicherebbe. Va convertito prima; `swagger2openapi` è la strada abituale.
Non ha seguito il mio `$ref` esterno.
Un `$ref` interno al documento viene risolto; uno che punta a un altro file vorrebbe dire leggere da un percorso che ha solo la propria macchina. Viene segnalato come nota, così si sa che il controllo è stato incompleto e non pulito.
Perché un `operationId` mancante è un avviso?
Perché i generatori lo usano per dare il nome alla funzione che producono per quell’operazione. Senza, il nome viene ricavato dal percorso e dal metodo, e cambia nel momento in cui cambia il percorso: una rinomina nella propria API diventa una rinomina in ogni client.
Può ricevere da
Da JSON a JSON Schema
JSON to JSON Schema
Deduce un JSON Schema da uno o più esempi, unendo le forme che incontra.
Validatore di JSON Schema
JSON Schema Validator
Valida un documento rispetto a un JSON Schema e riporta ogni errore con il percorso dell’istanza.
Da curl a codice
curl to Code
Converte un comando curl in fetch, axios, requests di Python, Go, PHP o PowerShell.
Confronto fra documenti OpenAPI
OpenAPI Diff
Confronta due documenti OpenAPI e separa le modifiche che rompono la compatibilità da quelle che aggiungono soltanto.
Dopo
Questi accettano ciò che produce questo strumento, così il risultato può passare direttamente.
Da curl a codice
curl to Code
Converte un comando curl in fetch, axios, requests di Python, Go, PHP o PowerShell.
Validatore di JSON Schema
JSON Schema Validator
Valida un documento rispetto a un JSON Schema e riporta ogni errore con il percorso dell’istanza.
Confronto fra documenti OpenAPI
OpenAPI Diff
Confronta due documenti OpenAPI e separa le modifiche che rompono la compatibilità da quelle che aggiungono soltanto.
Formattatore e validatore YAML
YAML Formatter & Validator
Riporta il YAML a un’indentazione coerente, lo valida e segnala gli errori di tabulazione e di ancora che rompono i parser.
Conversione JSON ⇄ CSV
JSON ⇄ CSV
Appiattisce il JSON annidato in colonne o ricostruisce gli oggetti da una tabella, con i nomi di colonna a percorso puntato.
Confronto fra due JSON
JSON Diff
Confronta due documenti JSON per struttura, ignorando l’ordine delle chiavi e riportando i percorsi aggiunti, tolti e cambiati.