OpenAPI 검증기 (Swagger 유효성 검사)

Swagger 2.0과 OpenAPI 3.0·3.1·3.2(YAML/JSON)를 브라우저에서 검증합니다. 공식 스키마, 파일 간 $ref, 경로 파라미터, 예제와 스키마 일치를 줄 번호와 함께 표시하며 업로드하지 않습니다.

  • 브라우저에서 처리
  • 도구 입력을 ZeroTool 서버에 업로드하지 않습니다
  • 무료 · 회원가입 불필요
.yaml, .yml, .json 파일을 열거나 끌어 놓으세요. 합계 50 MiB까지 지원하며 openapi 또는 swagger 필드가 있는 파일을 메인 문서로 선택합니다. 524,288자를 넘는 파일은 최대 300줄·49,152자의 읽기 전용 창으로 표시하고 검증은 전체 내용으로 합니다.

OpenAPI 또는 Swagger 문서를 붙여넣거나 파일을 여세요.

YAML이나 JSON을 붙여 넣으세요. 모든 파일의 합계가 2,097,152자 이하면 입력을 멈춘 뒤 500밀리초 후 자동 검증합니다. 더 큰 입력은 「검증」 또는 Ctrl/⌘+Enter를 누르세요.

검증 문제, 파일 위치, 문서 요약을 여기에 표시합니다.

추가 파일 이름은 메인 문서를 기준으로 $ref에 적힌 경로(예: schemas/pet.yaml)와 같아야 합니다. 「파일 추가」 또는 누락된 파일의 추가 버튼을 누르고 내용을 붙여 넣으세요. 추가 파일은 이 페이지에서 검증을 위해 읽으며 업로드하지 않고 참조 URL도 내려받지 않습니다.

각 파일 이름은 $ref에 적힌 경로(메인 문서 기준 상대 경로, 예: schemas/pet.yaml)로 정하세요. 파일은 업로드되지 않습니다.

예시·자세한 설명·자주 묻는 질문 실제 출력이 있는 예시, 다른 도구와의 차이, 자주 묻는 질문.

OpenAPI나 Swagger 문서를 붙여넣거나 파일·폴더를 여세요. 버전에 맞는 공식 JSON Schema로 구조를 검증하고, 파일 사이의 $ref를 따라가며, 스키마만으로는 표현할 수 없는 규칙도 확인합니다. 모든 문제에는 줄과 열이 붙고, 누르면 편집기에서 그 줄을 선택합니다.

공공데이터포털 Swagger 2.0 문서

공공데이터포털(data.go.kr)의 일부 API는 명세를 Swagger 2.0 문서로 제공합니다. 예를 들어 「예방접종센터 위치정보 API」 문서(infuser.odcloud.kr/oas/docs?namespace=15077586/v1, 2026-10-03 조회)를 넣으면 오류 3건과 OpenAPI 3 변환 안내가 나옵니다. 오류는 아래에 설명한 exclusiveMinimum 문제입니다. 이 문서는 Authorization 헤더(ApiKeyAuth)와 serviceKey 쿼리(ApiKeyAuth2) 두 가지 인증을 선언합니다. 아래 발췌본처럼 보안 요구사항의 이름을 잘못 쓰면 오류가 됩니다.

{
"swagger": "2.0",
"info": {"version": "1", "title": "예방접종센터 위치정보 API (발췌)"},
"host": "api.odcloud.kr",
"basePath": "/api",
"schemes": ["https"],
"securityDefinitions": {
  "ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "Authorization"},
  "ApiKeyAuth2": {"type": "apiKey", "in": "query", "name": "serviceKey"}
},
"paths": {
  "/15077586/v1/centers": {
    "get": {
      "parameters": [
        {"name": "page", "in": "query", "type": "integer", "format": "int64", "default": 1},
        {"name": "perPage", "in": "query", "type": "integer", "format": "int64", "default": 10}
      ],
      "responses": {"200": {"description": "성공적으로 수행 됨"}},
      "security": [{"ApiKeyAuth": []}, {"ApiKeyAuth3": []}]
    }
  }
}
}
2:3  정보  Swagger 2.0 문서이며 Swagger 2.0 스키마로 검증했습니다. OpenAPI 3로 옮기려면 변환한 뒤(예: npx swagger2openapi swagger.yaml -o openapi.yaml) 결과를 다시 검증하세요.
9:5  경고  보안 정의 "ApiKeyAuth2"을(를) 참조하는 곳이 없습니다.
19:43  오류  보안 스킴 "ApiKeyAuth3"이(가) securityDefinitions에 선언되지 않았습니다.

원본 문서의 쿼리 파라미터 세 개(page, perPage, returnType)에는 minimum 없이 "exclusiveMinimum": false가 붙어 있습니다. Swagger 2.0이 따르는 JSON Schema draft 4는 「exclusiveMinimum이 있으면 minimum도 있어야 한다」(MUST)고 정하므로, 이 도구는 세 곳을 각각 오류로 냅니다. "exclusiveMinimum": false를 지우면 통과합니다. Spectral 6.17.0은 같은 규칙을 기본값(default)이 있는 두 파라미터의 예제 확인에서만 오류로 내고, Redocly CLI 2.57.0은 보고하지 않습니다.

같은 경로 템플릿과 예제 값

/members/{memberId}와 /members/{id}처럼 파라미터 이름만 다른 경로는 같은 URL에 맞기 때문에 사양에서 허용하지 않습니다(Paths Object의 MUST). 예제에서는 enum에 없는 등급 값이 경고로 나옵니다.

openapi: 3.0.3
info:
title: 회원 API
version: 1.0.0
paths:
/members/{memberId}:
  get:
    parameters:
      - {name: memberId, in: path, required: true, schema: {type: string}}
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Member"
            example:
              memberId: M-0001
              phone: 010-1234-5678
              grade: VVIP
/members/{id}:
  delete:
    parameters:
      - {name: id, in: path, required: true, schema: {type: string}}
    responses:
      "204": {description: 삭제됨}
components:
schemas:
  Member:
    type: object
    required: [memberId, phone]
    properties:
      memberId: {type: string}
      phone: {type: string, pattern: "^01[0-9]-?[0-9]{3,4}-?[0-9]{4}$"}
      grade: {type: string, enum: [BASIC, VIP]}
  Address:
    type: object
20:17  경고  예제가 스키마와 맞지 않습니다 (/grade): 다음 중 하나여야 합니다: "BASIC", "VIP".
21:3  오류  경로 "/members/{id}"는 "/members/{memberId}"와 같은 템플릿입니다(파라미터 이름만 다름). 사양상 둘 다 둘 수 없습니다.
36:5  경고  스키마 "Address"을(를) 참조하는 곳이 없습니다.

중복된 파라미터

같은 이름과 위치(in)의 파라미터는 한 목록에 한 번만 올 수 있습니다. 공식 스키마는 이 규칙을 확인하지 않으므로, 아래 문서는 스키마 검증만으로는 통과합니다. info.version의 따옴표 없는 날짜는 YAML 1.2 Core Schema에 따라 문자열로 읽으므로 오류가 아닙니다.

openapi: 3.1.0
info:
title: 결제 API
version: 2026-10-02
paths:
/payments:
  post:
    parameters:
      - {name: Idempotency-Key, in: header, required: true, schema: {type: string}}
      - {name: Idempotency-Key, in: header, schema: {type: string}}
    responses:
      "200": {description: OK}
10:11  오류  파라미터 "Idempotency-Key"(in: header)이(가) 이 목록의 1번째에도 있습니다. 같은 이름과 위치는 한 번만 쓸 수 있습니다.

확인하는 규칙

규칙단계근거
필수·허용되지 않는 필드, 타입, 파라미터와 응답의 형태오류버전별 공식 JSON Schema
3.1·3.2의 스키마 객체(예: 속성에 쓴 required: true)오류JSON Schema 2020-12 메타스키마
로컬 $ref 대상이 존재함(추가한 다른 파일 포함)오류Reference Object
경로 템플릿과 in: path 파라미터의 대응, 이름만 다른 경로, 중복 파라미터·operationId·태그 이름오류Paths Object, Parameter Object의 MUST
보안 요구사항의 스킴이 선언됨오류Security Requirement Object
서버 변수 기본값이 enum 안에 있음3.1부터 오류, 3.0은 경고Server Variable Object
불리언 exclusiveMinimum / exclusiveMaximum과 같은 객체에 minimum / maximum이 없음(스키마 객체, 2.0에서는 body가 아닌 Parameter·Header·Items Object도)2.0은 오류, 3.0은 경고2.0은 JSON Schema draft 4(§5.1.2.1, §5.1.3.1: 함께 써야 함, MUST), 3.0이 따르는 Wright draft 00은 이 MUST를 없앴으므로 단독으로는 효과가 없을 뿐입니다. 공식 스키마, Redocly CLI 2.57.0, Spectral 6.17.0은 이 항목을 따로 확인하지 않습니다
예제와 스키마의 일치, 참조되지 않은 컴포넌트, 정의되지 않았거나 쓰이지 않는 서버 변수, 3.1의 nullable경고사양의 SHOULD와 Redocly·Spectral도 보고하는 흔한 실수

다른 도구와 비교

2026-10-02에 같은 시험 문서로 비교했습니다. 선언하지 않은 경로 파라미터, 선언하지 않은 보안 스킴, 이름만 다른 두 경로, 속성의 required: true라는 네 가지 오류와, 따옴표 없는 날짜로 쓴 info.version이 들어 있습니다.

  • Redocly CLI 2.57.0과 Spectral 6.17.0은 네 가지를 모두 찾았고, summary나 4XX 응답 같은 스타일 규칙도 많이 냅니다. swagger-parser 13.1.0은 유효하다고 판정했습니다.
  • Swagger Editor 5.8.9(editor.swagger.io)는 브라우저에서 동작하며 경로 파라미터와 required 문제는 찾았지만, 같은 템플릿의 경로와 선언되지 않은 스킴은 표시하지 않았습니다.
  • DevUtilities의 OpenAPI 검증기는 서버로 보내지 않고 동작하지만 결과는 「VALID WITH WARNINGS」였고, 경고는 servers가 없다는 한 건뿐이었습니다.

제한

  • 이름 짓기나 설명 같은 스타일 규칙은 다루지 않습니다. 팀 규칙은 이 도구 다음에 Redocly CLI나 Spectral로 확인하세요.
  • $ref의 URL은 가져오지 않고 정보로만 표시하며 확인하지 않습니다. 빠진 것이 파일 참조라면 그 파일을 추가하세요. 앵커 참조(#name)는 확인하지 않습니다.
  • JSON이 아닌 미디어 타입(application/xml 등)의 문자열 예제는 직렬화된 본문으로 보고 스키마와 비교하지 않습니다.
  • 매우 큰 문서는 예제 확인을 4초에서 멈추고 알려 줍니다. 2,097,152자를 넘는 입력은 「검증」을 눌렀을 때 확인하고, 합계 50 MiB가 넘는 파일은 불러오지 않습니다.
  • 연 파일이 512 K자를 넘으면 전체를 검증하지만 편집 칸에는 최대 300줄·49,152자를 읽기 전용으로 보여 줍니다. 10 MB 정도를 편집 칸에 넣으면 페이지가 0.5초쯤 멈추기 때문입니다. 줄 번호를 누르면 그 줄로 이동하고, 「전체 복사」「다운로드」「전체 편집(느림)」으로 전체 내용을 다룰 수 있습니다. 직접 그만큼 붙여 넣으면 여전히 페이지가 멈춥니다.
  • YAML은 js-yaml 4.3.2로 읽습니다. 중첩이 100단계를 넘거나, 병합 키가 처리하는 매핑과 키가 모두 10,000개를 넘거나, 병합 키 하나에 매핑을 100개 넘게 나열한 문서는 멈추고, 오류에 한도와 줄 번호가 나옵니다.

관련 도구: 타입을 만드는 OpenAPI → TypeScript 생성기, 요청 JSON을 확인하는 JSON Schema 유효성 검사기, 들여쓰기 오류를 찾는 YAML 유효성 검사기.

FAQ

어떤 버전을 지원하나요?

Swagger 2.0과 OpenAPI 3.0·3.1·3.2입니다. swagger 또는 openapi 필드를 읽고 그 버전의 공식 JSON Schema로 검증합니다. Swagger 2.0은 OpenAPI Initiative 저장소의 스키마, 3.0(2024-10-18)·3.1(2026-08-03)·3.2(2026-08-30)는 spec.openapis.org가 공개한 스키마입니다.

API 명세가 서버로 전송되나요?

아니요. 파싱과 모든 확인은 브라우저 안에서(Web Worker, Worker를 시작할 수 없으면 페이지 자체에서) 하며, 명세를 업로드하지도 브라우저 저장소에 저장하지도 않습니다. $ref의 URL은 가져오지 않고, 「다른 파일」에 추가한 파일도 이 페이지 안에서만 씁니다. 텍스트나 파일 편집 확정, 파일 작업, 예시 또는 “검증”으로 확인을 완료하면 도구 이름과 검증 오류 유무에 따른 validate_success 또는 validate_error만 기록합니다. 입력 중에도 결과는 갱신하지만 사용 이벤트는 기록하지 않습니다. 복원과 초기 표시, 같은 검증 결과, Worker 실패, 오래된 응답은 이벤트를 추가하지 않습니다. 명세 내용은 포함하지 않습니다.

$ref로 나눈 여러 파일도 함께 확인할 수 있나요?

네. 여러 파일이나 폴더를 한 번에 열거나, 「다른 파일」에 $ref와 같은 경로(예: schemas/pet.yaml)로 추가하세요. 참조를 파일 사이에서 해석하고, 문제는 실제 내용이 있는 파일과 줄에 표시합니다. 추가하지 않은 파일과 URL 참조는 정보로 나옵니다.

오류와 경고는 무엇이 다른가요?

오류는 사양의 MUST나 공식 스키마를 어긴 것이라 다른 도구가 문서를 거부할 수 있습니다. 경고는 SHOULD 규칙과 흔한 실수(예제가 스키마와 다름, 참조되지 않은 컴포넌트, 정의되지 않은 서버 변수 등)이고, 정보는 확인하지 않은 항목과 주의할 값을 보여 줍니다.

info.version: 2024-01-15가 여기서는 통과하는데 다른 검증기에서는 오류가 나는 이유는 무엇인가요?

이 도구는 YAML을 YAML 1.2 Core Schema로 읽습니다(Redocly CLI, Spectral, swagger-parser와 같음). 그래서 따옴표 없는 날짜도 문자열로 남습니다. YAML 1.1 타임스탬프 규칙으로 읽는 파서는 이를 날짜로 바꾸고, 스키마가 info.version을 거부합니다. "2024-01-15"처럼 따옴표로 감싸면 어느 파서에서나 문자열로 읽힙니다.

공공데이터포털의 Swagger 2.0 문서도 검증되나요?

네. Swagger 2.0 문서는 Swagger 2.0 스키마로 검증하고, OpenAPI 3과 같은 참조·경로 파라미터·보안 규칙도 적용하며, OpenAPI 3로 옮기는 방법을 정보로 안내합니다. 예를 들어 「예방접종센터 위치정보 API」 문서(2026-10-03 조회)는 minimum 없이 쓴 "exclusiveMinimum": false 때문에 오류 3건이 나옵니다.