JSON Schema를 OpenAPI 스키마로 변환 — Numio
JSON Schema(draft-04 이상)를 OpenAPI 3.0 Schema Object로 변환합니다. "null"이 포함된 type 배열은 "nullable: true"로, const는 항목이 하나인 enum으로, examples는 단일 example로 바뀝니다.
draft-07 스키마로 페이로드를 검증하고 있고, 같은 모델을 OpenAPI 3.0 문서의 components/schemas 아래에서도 써야 할 때.
JSON Schema
이럴 때 사용하세요
- draft-07 스키마로 페이로드를 검증하고 있고, 같은 모델을 OpenAPI 3.0 문서의 components/schemas 아래에서도 써야 할 때.
- OpenAPI 3.0 도구가 "type": ["string", "null"]을 거부해서 nullable 필드를 다시 써야 할 때.
사용 방법
- JSON Schema 패널에 JSON Schema를 붙여 넣습니다. 페이지가 전송 전에 파싱하므로 유효한 JSON이어야 합니다.
- 스키마는 /api/json-schema-to-openapi-schema로 전송되어 서버에서 변환되며, 패널에 이를 알리는 안내가 표시됩니다.
- Open API Schema 패널에서 결과를 복사해 OpenAPI 파일의 components/schemas 아래에 넣습니다.
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"
]
}세부 정보 및 제한 사항
입력은 변환을 위해 서버 라우트(/api/json-schema-to-openapi-schema)로 전송되며, 브라우저에서만 처리되지 않습니다. Next.js API 라우트는 기본적으로 최대 1 MB의 요청 본문을 받습니다.
$schema 키워드는 제거됩니다. 숫자 값의 exclusiveMinimum/exclusiveMaximum은 OpenAPI 3.0 형식인 minimum/maximum과 불리언 플래그로 바뀝니다.
$ref 값은 그대로 남고 definitions는 components/schemas로 옮겨지지 않으므로, 참조 경로는 직접 고쳐야 합니다.
대상은 OpenAPI 3.0입니다. OpenAPI 3.1은 이미 JSON Schema를 그대로 사용하므로 보통 변환이 필요 없습니다.
FAQ
nullable 타입은 어떻게 변환되나요?
["number", "null"] 같은 type 배열은 예시처럼 "type": "number"와 "nullable": true가 됩니다.
$ref 참조를 해석하나요?
아니요. 페이지는 역참조를 하지 않으며, "$ref": "#/definitions/Tag"와 definitions 블록은 그대로 복사됩니다.
const와 examples는 어떻게 되나요?
const는 값이 하나인 enum이 되고, examples 배열은 첫 번째 항목을 사용한 단일 example로 대체됩니다.