Zum Inhalt springen
Numio

JSON Schema in ein OpenAPI-Schema umwandeln — Numio

Wandelt ein JSON Schema (draft-04 und neuer) in ein OpenAPI 3.0 Schema Object um. Type-Arrays mit "null" werden zu "nullable: true", const wird zu einem enum mit einem Eintrag und examples zu einem einzelnen example.

Du validierst Payloads mit einem draft-07-Schema und brauchst dasselbe Modell unter components/schemas in einem OpenAPI-3.0-Dokument.

JSON Schema

Open API Schema

Wann sie hilft

  • Du validierst Payloads mit einem draft-07-Schema und brauchst dasselbe Modell unter components/schemas in einem OpenAPI-3.0-Dokument.
  • Dein OpenAPI-3.0-Tooling lehnt "type": ["string", "null"] ab, und du musst nullable Felder umschreiben.

Anwendung

  1. Füge ein JSON Schema in das Panel JSON Schema ein; es muss gültiges JSON sein, da die Seite es vor dem Senden parst.
  2. Das Schema wird an /api/json-schema-to-openapi-schema gesendet und auf dem Server konvertiert; das Panel zeigt einen entsprechenden Hinweis.
  3. Kopiere das Ergebnis aus dem Panel Open API Schema und füge es in deiner OpenAPI-Datei unter components/schemas ein.

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

OpenAPI 3.0 Schema Object

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

Details und Einschränkungen

Die Seite sendet deine Eingabe zur Konvertierung an eine Server-Route (/api/json-schema-to-openapi-schema); sie wird nicht nur im Browser verarbeitet. Next.js-API-Routen akzeptieren standardmäßig Request-Bodys bis 1 MB.

Das Schlüsselwort $schema wird entfernt. Numerische exclusiveMinimum/exclusiveMaximum werden in die OpenAPI-3.0-Form umgeschrieben: minimum/maximum plus ein boolesches Flag.

$ref-Werte bleiben unverändert, und definitions werden nicht nach components/schemas verschoben; Referenzpfade musst du daher selbst anpassen.

Ziel ist OpenAPI 3.0. OpenAPI 3.1 verwendet JSON Schema bereits direkt und braucht meist keine Konvertierung.

FAQ

Wie werden nullable Typen konvertiert?

Ein Type-Array wie ["number", "null"] wird zu "type": "number" mit "nullable": true, wie im Beispiel.

Werden $ref-Referenzen aufgelöst?

Nein. Die Seite dereferenziert nicht; "$ref": "#/definitions/Tag" und der definitions-Block werden unverändert übernommen.

Was passiert mit const und examples?

const wird zu einem enum mit einem Wert, und das examples-Array wird durch ein einzelnes example aus seinem ersten Element ersetzt.

Spezifikationen und Referenzen