Vai al contenuto
Numio

Convertitore da schema JSON a specifiche OpenAPI — Numio

Converte uno schema JSON (bozza-04 e successive) in un oggetto schema OpenAPI 3.0. Gli array di tipi contenenti "null" diventano "nullable: true", const diventa un'enumerazione a un elemento e gli esempi diventano un singolo esempio.

Convalidi i payload con uno schema draft-07 e hai bisogno dello stesso modello in componenti/schemi in un documento OpenAPI 3.0.

JSON Schema

Open API Schema

Quando usarlo

  • Convalidi i payload con uno schema draft-07 e hai bisogno dello stesso modello in componenti/schemi in un documento OpenAPI 3.0.
  • I tuoi strumenti OpenAPI 3.0 rifiutano "type": ["string", "null"] e devi riscrivere i campi nullable.

Come si usa

  1. Incolla uno schema JSON nel pannello Schema JSON; deve essere JSON valido perché la pagina lo analizza prima dell'invio.
  2. Lo schema viene convertito localmente in un Web Worker del browser. Non viene inviato a un server.
  3. Copia il risultato dal pannello Apri schema API e posizionalo sotto Componenti/schemi nel file OpenAPI.

Schema JSON

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "kind": { "const": "invoice" },
    "total": { "type": ["number", "null"], "exclusiveMinimum": 0 },
    "notes": { "type": "string", "examples": ["Net 30"] }
  },
  "required": ["kind"]
}

Oggetto dello schema OpenAPI 3.0

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "invoice"
      ]
    },
    "total": {
      "type": "number",
      "exclusiveMinimum": true,
      "nullable": true,
      "minimum": 0
    },
    "notes": {
      "type": "string",
      "example": "Net 30"
    }
  },
  "required": [
    "kind"
  ]
}

Dettagli e limiti

La conversione avviene localmente in un Web Worker del browser; l’input non viene caricato su un server. Al primo utilizzo il browser scarica il modulo di conversione necessario.

La parola chiave $schema viene rimossa. I numeri exclusiveMinimum/exclusiveMaximum vengono riscritti nel formato OpenAPI 3.0: minimo/massimo più un flag booleano.

I valori $ref vengono lasciati così come sono e le definizioni non vengono spostate in componenti/schemi, quindi è necessario correggere manualmente i percorsi di riferimento.

L'obiettivo è OpenAPI 3.0. OpenAPI 3.1 utilizza già direttamente lo schema JSON e di solito non necessita di conversione.

FAQ

Come vengono convertiti i tipi nullable?

Un array di tipi come ["number", "null"] diventa "type": "number" con "nullable": true, come nell'esempio.

Risolve i riferimenti $ref?

No. La pagina non dereferenzia; "$ref": "#/definitions/Tag" e il blocco delle definizioni vengono copiati senza modifiche.

Cosa succede a const ed esempi?

const diventa un enum con un solo valore e l'array examples viene sostituito da un singolo example ricavato dal primo elemento.

Specifiche e riferimenti