Aller au contenu
Numio

Convertir JSON Schema en schéma OpenAPI — Numio

Convertit un JSON Schema (draft-04 et ultérieurs) en Schema Object OpenAPI 3.0. Les tableaux de types contenant "null" deviennent "nullable: true", const devient un enum à un seul élément et examples devient un seul example.

Vous validez des payloads avec un schéma draft-07 et avez besoin du même modèle sous components/schemas dans un document OpenAPI 3.0.

JSON Schema

Open API Schema

Quand l’utiliser

  • Vous validez des payloads avec un schéma draft-07 et avez besoin du même modèle sous components/schemas dans un document OpenAPI 3.0.
  • Vos outils OpenAPI 3.0 rejettent "type": ["string", "null"] et vous devez réécrire les champs nullables.

Mode d’emploi

  1. Collez un JSON Schema dans le panneau JSON Schema ; il doit s’agir de JSON valide, car la page l’analyse avant de l’envoyer.
  2. Le schéma est envoyé à /api/json-schema-to-openapi-schema et converti sur le serveur ; le panneau affiche un avis qui le signale.
  3. Copiez le résultat du panneau Open API Schema et placez-le sous components/schemas dans votre fichier OpenAPI.

JSON Schema

{
  "$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"]
}

Schema Object 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"
  ]
}

Détails et limites

La page envoie votre saisie à une route serveur (/api/json-schema-to-openapi-schema) pour la conversion ; elle n’est pas traitée uniquement dans le navigateur. Par défaut, les routes API de Next.js acceptent des corps de requête jusqu’à 1 Mo.

Le mot-clé $schema est supprimé. Les exclusiveMinimum/exclusiveMaximum numériques sont réécrits sous la forme OpenAPI 3.0 : minimum/maximum plus un indicateur booléen.

Les valeurs $ref sont laissées telles quelles et les definitions ne sont pas déplacées vers components/schemas : vous devez corriger vous-même les chemins de référence.

La cible est OpenAPI 3.0. OpenAPI 3.1 utilise déjà JSON Schema directement et ne nécessite généralement aucune conversion.

FAQ

Comment les types nullables sont-ils convertis ?

Un tableau de types comme ["number", "null"] devient "type": "number" avec "nullable": true, comme dans l’exemple.

Les références $ref sont-elles résolues ?

Non. La page ne déréférence pas ; "$ref": "#/definitions/Tag" et le bloc definitions sont recopiés sans modification.

Que deviennent const et examples ?

const devient un enum à une seule valeur, et le tableau examples est remplacé par un seul example tiré de son premier élément.

Spécifications et références