Pular para o conteúdo
Numio

Converter JSON Schema em esquema OpenAPI — Numio

Converte um JSON Schema (draft-04 ou posterior) em um Schema Object do OpenAPI 3.0. Arrays de tipos que contêm "null" viram "nullable: true", const vira um enum de um item e examples vira um único example.

Você valida payloads com um schema draft-07 e precisa do mesmo modelo em components/schemas de um documento OpenAPI 3.0.

JSON Schema

Open API Schema

Quando usar

  • Você valida payloads com um schema draft-07 e precisa do mesmo modelo em components/schemas de um documento OpenAPI 3.0.
  • Suas ferramentas de OpenAPI 3.0 rejeitam "type": ["string", "null"] e você precisa reescrever os campos anuláveis.

Como usar

  1. Cole um JSON Schema no painel JSON Schema; ele precisa ser um JSON válido, porque a página o analisa antes de enviar.
  2. O schema é enviado para /api/json-schema-to-openapi-schema e convertido no servidor; o painel mostra um aviso informando isso.
  3. Copie o resultado do painel Open API Schema e coloque-o em components/schemas no seu arquivo 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 do 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"
  ]
}

Detalhes e limitações

A página envia sua entrada para uma rota do servidor (/api/json-schema-to-openapi-schema) para conversão; ela não é processada apenas no navegador. As rotas de API do Next.js aceitam por padrão corpos de requisição de até 1 MB.

A palavra-chave $schema é removida. exclusiveMinimum/exclusiveMaximum numéricos são reescritos na forma do OpenAPI 3.0: minimum/maximum mais um flag booleano.

Os valores de $ref são mantidos como estão e as definitions não são movidas para components/schemas, então você mesmo precisa corrigir os caminhos de referência.

O alvo é o OpenAPI 3.0. O OpenAPI 3.1 já usa JSON Schema diretamente e normalmente não precisa de conversão.

FAQ

Como os tipos anuláveis são convertidos?

Um array de tipos como ["number", "null"] vira "type": "number" com "nullable": true, como no exemplo.

Ele resolve referências $ref?

Não. A página não faz dereferência; "$ref": "#/definitions/Tag" e o bloco definitions são copiados sem alteração.

O que acontece com const e examples?

const vira um enum com um único valor, e o array examples é substituído por um único example tirado do primeiro item.

Especificações e referências