Przejdź do treści
Numio

Konwerter JSON Schema na specyfikacje OpenAPI — Numio

Konwertuje JSON Schema (draft-04 i nowsze) na obiekt schematu OpenAPI 3.0. Tablice typów zawierające "null" stają się "nullable: true", const staje się jednoelementowym enum, a examples pojedynczym example.

Sprawdzasz ładunki za pomocą schematu wersji roboczej 07 i potrzebujesz tego samego modelu w komponentach/schematach w dokumencie OpenAPI 3.0.

JSON Schema

Open API Schema

Kiedy go używać

  • Sprawdzasz ładunki za pomocą schematu wersji roboczej 07 i potrzebujesz tego samego modelu w komponentach/schematach w dokumencie OpenAPI 3.0.
  • Narzędzia OpenAPI 3.0 odrzucają "type": ["string", "null"] i potrzebujesz przekształcić pola dopuszczające null.

Jak używać

  1. Wklej schemat JSON do panelu schematu JSON; musi być prawidłowy JSON, ponieważ strona analizuje go przed wysłaniem.
  2. Schemat jest konwertowany lokalnie w Web Workerze w przeglądarce, bez wysyłania go na serwer.
  3. Skopiuj wynik z panelu Otwórz schemat API i umieść go w sekcji Komponenty/schematy w pliku OpenAPI.

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

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

Szczegóły i ograniczenia

Konwersja odbywa się lokalnie w Web Workerze w przeglądarce. Dane wejściowe nie są wysyłane na serwer konwersji. Wymagane moduły są pobierane przy pierwszym użyciu narzędzia.

Słowo kluczowe $schema jest usuwane. Liczbowe exclusiveMinimum/exclusiveMaximum są przekształcane do postaci OpenAPI 3.0: minimum/maximum oraz flaga logiczna.

Wartości $ref pozostają bez zmian, a definicje nie są przenoszone do komponentów/schematów, dlatego musisz samodzielnie naprawić ścieżki referencyjne.

Celem jest OpenAPI 3.0. OpenAPI 3.1 korzysta już bezpośrednio ze schematu JSON i zwykle nie wymaga konwersji.

FAQ

W jaki sposób konwertowane są typy dopuszczające wartość null?

Tablica typów, taka jak ["number", "null"] staje się "type": "number" z "nullable": true, jak w przykładzie.

Czy rozwiązuje odniesienia $ref?

Nie. Strona nie zawiera odwołań; "$ref": "#/definitions/Tag" i blok definicji zostaną skopiowane bez zmian.

Co dzieje się z const i examples?

const staje się enum z jedną wartością, a tablica examples jest zastępowana pojedynczym example pobranym z jej pierwszego elementu.

Specyfikacje i referencje