Saltar al contenido
Numio

Convertir JSON Schema a un esquema OpenAPI — Numio

Convierte un JSON Schema (draft-04 o posterior) en un Schema Object de OpenAPI 3.0. Los arrays de tipos que contienen "null" pasan a "nullable: true", const pasa a un enum de un solo elemento y examples pasa a un único example.

Validas payloads con un esquema draft-07 y necesitas el mismo modelo en components/schemas de un documento OpenAPI 3.0.

JSON Schema

Open API Schema

Cuándo usarla

  • Validas payloads con un esquema draft-07 y necesitas el mismo modelo en components/schemas de un documento OpenAPI 3.0.
  • Tus herramientas de OpenAPI 3.0 rechazan "type": ["string", "null"] y necesitas reescribir los campos anulables.

Cómo usarla

  1. Pega un JSON Schema en el panel JSON Schema; debe ser JSON válido, porque la página lo analiza antes de enviarlo.
  2. El esquema se envía a /api/json-schema-to-openapi-schema y se convierte en el servidor; el panel muestra un aviso que lo indica.
  3. Copia el resultado del panel Open API Schema y colócalo en components/schemas de tu archivo 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 de 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"
  ]
}

Detalles y limitaciones

La página envía tu entrada a una ruta del servidor (/api/json-schema-to-openapi-schema) para convertirla; no se procesa solo en el navegador. Las rutas API de Next.js aceptan por defecto cuerpos de solicitud de hasta 1 MB.

Se elimina la palabra clave $schema. Los exclusiveMinimum/exclusiveMaximum numéricos se reescriben a la forma de OpenAPI 3.0: minimum/maximum más un indicador booleano.

Los valores de $ref se dejan tal cual y las definitions no se mueven a components/schemas, así que debes corregir tú las rutas de referencia.

El destino es OpenAPI 3.0. OpenAPI 3.1 ya usa JSON Schema directamente y normalmente no necesita conversión.

FAQ

¿Cómo se convierten los tipos anulables?

Un array de tipos como ["number", "null"] pasa a "type": "number" con "nullable": true, como en el ejemplo.

¿Resuelve las referencias $ref?

No. La página no desreferencia; "$ref": "#/definitions/Tag" y el bloque definitions se copian sin cambios.

¿Qué pasa con const y examples?

const pasa a un enum con un solo valor, y el array examples se sustituye por un único example tomado de su primer elemento.

Especificaciones y referencias