OpenAPI 검증기: API Spec 린트

OpenAPI 검증기란?

OpenAPI 검증기는 OpenAPI 3.x 및 Swagger 2.0 사양 파일을 파싱하고 검증하는 브라우저 기반 도구입니다. JSON 또는 YAML spec을 붙여넣고 Validate를 클릭하면 몇 초 내에 spec이 구조적으로 유효한지, 경로 및 작업 수, SDK 생성기와 개발자 문서 도구에 중요한 누락 필드에 대한 경고 목록을 확인할 수 있습니다.

도구는 요청 시 로드되는 @readme/openapi-parser 라이브러리를 사용하여 브라우저에서 완전히 실행됩니다. spec 내용은 어떤 서버로도 전송되지 않습니다. 계정 없이 무료로 사용할 수 있습니다.

버전 관리에 spec을 커밋하기 전, API 문서를 게시하기 전, 또는 Swagger UI, Stoplight, SDK 생성기 같은 하위 도구가 거부하는 spec을 디버깅할 때 사용하세요.

주요 기능

OpenAPI 3.x 및 Swagger 2.0 지원: 검증기는 두 형식을 모두 수용합니다. 기반 @readme/openapi-parser 라이브러리가 OpenAPI 3.1을 포함한 두 사양 버전을 처리합니다.
JSON 및 YAML 입력: 도구가 먼저 JSON.parse를 시도하고, 실패하면 YAML 입력을 위해 js-yaml로 폴백합니다.
정확한 오류 메시지의 구조 검증: 검증 실패 시 파서의 오류 메시지가 줄바꿈으로 분리되어 개별적으로 표시됩니다.
린팅 경고: spec이 구조적으로 유효하더라도 세 가지 일반적인 품질 문제를 검사합니다: 누락된 info.description, description과 summary가 모두 없는 작업, operationId가 없는 작업.
엔드포인트 및 작업 수: 성공적인 검증 후 요약 타일에 API 제목, 버전 문자열, 총 경로 수, 총 작업 수가 표시됩니다.
예제 로드 버튼: 단일 /users GET 엔드포인트가 있는 최소한의 완전한 OpenAPI 3.0 spec을 삽입합니다.
검증 이력: 이전 spec이 브라우저의 IndexedDB에 저장됩니다(서포터 기능).
100% 클라이언트 사이드 처리: 파서와 검증기가 브라우저에서 실행됩니다.

OpenAPI 검증기 사용 방법

1단계: Spec 붙여넣기

"OpenAPI Specification (JSON or YAML)" 레이블이 있는 큰 텍스트 영역에 spec 내용을 붙여넣으세요. YAML의 경우 상단에 버전 선언을 포함하세요(openapi: "3.0.0" 또는 swagger: "2.0").

도구를 먼저 확인하고 싶다면 텍스트 영역 우측 상단의 "Load Example" 버튼을 클릭하세요.

2단계: Validate Spec 클릭

텍스트 영역 아래의 "Validate Spec" 버튼을 클릭합니다. 파서 실행 중 버튼에 "Validating..."이 표시됩니다.

3단계: 검증 결과 확인

결과 패널이 두 제목 중 하나와 함께 나타납니다:

"✓ Valid OpenAPI Specification"(녹색) — spec이 구조 검증을 통과했습니다.
"✗ Validation Failed"(빨간색) — spec에 수정이 필요한 구조 오류가 있습니다.

4단계: 요약 타일 읽기 (유효한 Spec)

검증을 통과한 spec에 네 개의 요약 타일이 표시됩니다:

Title — info.title의 값
Version — info.version의 값
Paths — 경로 항목의 총 수
Operations — HTTP 메서드+경로 조합의 총 수

5단계: 경고 처리

유효한 spec에서도 세 가지 경고 유형이 표시됩니다:

누락된 info.description — spec에 전체적인 API 설명이 없습니다.
description 또는 summary가 없는 작업 — 카운트로 보고됩니다.
operationId가 없는 작업 — SDK 생성기가 생성된 메서드 이름에 operationId를 사용합니다.

실용적인 예시

예시 1: 누락된 필수 필드 찾기

존재하지 않는 스키마 정의를 가리키는 $ref를 참조하는 Swagger 2.0 spec을 붙여넣으면:

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

예시 2: 품질 경고가 있는 유효한 Spec

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

예시 3: 대규모 Spec 한눈에 확인

500개 경로의 내부 API spec을 붙여넣으면 요약 타일에 "Paths: 147"과 "Operations: 312"가 표시됩니다.

팁과 모범 사례

모든 구조 변경 후 검증하세요. 새 경로 추가, $ref 변경, 스키마 수정은 오류를 도입할 수 있습니다. 검증은 2초 미만입니다.

operationId 경고를 SDK 워크플로우의 차단 요인으로 취급하세요. 설정하지 않으면 생성된 메서드 이름이 경로에서 파생됩니다.

예제를 템플릿으로 사용하세요. 내장 예제는 완전하고 유효한 최소한의 OpenAPI 3.0 spec입니다.

구조적 유효성과 의미적 정확성을 구분하세요. 검증기는 spec이 OpenAPI 스키마를 따르는지 확인하지만, 실제 API를 정확히 기술하는지는 확인하지 않습니다.

목록 위에서 아래로 오류를 수정하세요. 하나의 스키마 정의 누락이 spec 전체에 연쇄 $ref 오류를 일으킬 수 있습니다.

일반적인 문제 및 문제 해결

"Parse error: ..." — 입력이 유효한 JSON도 YAML도 아닙니다. 일반적인 원인: JSON의 후행 쉼표, 일관되지 않은 YAML 들여쓰기, YAML 들여쓰기의 탭 문자.

Swagger UI가 수용하는 spec에서 검증이 실패함. Swagger UI는 오류에 관대합니다. 이 검증기는 엄격한 스키마 검증을 적용합니다.

설명 추가 후에도 경고가 표시됨. info 내부에 description을 추가했는지 확인하세요.

첫 사용 시 도구가 느림. 라이브러리가 첫 검증 클릭 시 동적으로 로드됩니다.

개인정보 보호 및 보안

OpenAPI 검증기는 spec을 완전히 브라우저에서 처리합니다. @readme/openapi-parser 라이브러리가 로컬에서 실행되며, spec 내용은 외부 서비스나 서버로 전송되지 않습니다. 페이지와 파서 라이브러리가 로드된 후 완전히 오프라인으로 작동합니다.

자주 묻는 질문

OpenAPI 검증기는 무료인가요? 네. 비용, 계정, 사용 제한이 없습니다.

어떤 OpenAPI 버전이 지원되나요? Swagger 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x.

YAML을 붙여넣을 수 있나요? 두 형식 모두 작동합니다.

도구가 실제 API 엔드포인트를 검증하나요? 아니요. spec 파일이 구조적으로 올바른지만 확인합니다.

Swagger UI에서 작동하는데 여기서 실패하는 이유는? Swagger UI는 오류에 관대하게 spec을 렌더링합니다. 이 검증기는 엄격한 스키마 검증을 적용합니다.

"operationId required for SDK generation"의 의미는? SDK 생성기가 operationId 값을 기반으로 메서드 이름을 지정합니다. 없으면 경로에서 메서드 이름이 구성됩니다.

경고에 오탐이 있나요? 세 가지 경고 검사는 보수적입니다. info.description 검사는 필드가 없거나 비어 있을 때만 트리거됩니다.

붙여넣기 대신 spec 파일을 검증할 수 있나요? 도구는 붙여넣은 텍스트만 수용합니다. 파일 업로드 버튼이 없습니다.

이력 패널이 spec 내용을 저장하나요? 네. 브라우저의 IndexedDB 이력에 로컬로 저장됩니다.

빈 spec을 붙여넣으면 어떻게 되나요? 텍스트 영역이 비어 있으면 Validate 버튼이 비활성화됩니다.

OpenAPI 검증기란?

버전 관리에 spec을 커밋하기 전, API 문서를 게시하기 전, 또는 Swagger UI, Stoplight, SDK 생성기 같은 하위 도구가 거부하는 spec을 디버깅할 때 사용하세요.

주요 기능

OpenAPI 3.x 및 Swagger 2.0 지원: 검증기는 두 형식을 모두 수용합니다. 기반 @readme/openapi-parser 라이브러리가 OpenAPI 3.1을 포함한 두 사양 버전을 처리합니다.
JSON 및 YAML 입력: 도구가 먼저 JSON.parse를 시도하고, 실패하면 YAML 입력을 위해 js-yaml로 폴백합니다.
정확한 오류 메시지의 구조 검증: 검증 실패 시 파서의 오류 메시지가 줄바꿈으로 분리되어 개별적으로 표시됩니다.
린팅 경고: spec이 구조적으로 유효하더라도 세 가지 일반적인 품질 문제를 검사합니다: 누락된 info.description, description과 summary가 모두 없는 작업, operationId가 없는 작업.
엔드포인트 및 작업 수: 성공적인 검증 후 요약 타일에 API 제목, 버전 문자열, 총 경로 수, 총 작업 수가 표시됩니다.
예제 로드 버튼: 단일 /users GET 엔드포인트가 있는 최소한의 완전한 OpenAPI 3.0 spec을 삽입합니다.
검증 이력: 이전 spec이 브라우저의 IndexedDB에 저장됩니다(서포터 기능).
100% 클라이언트 사이드 처리: 파서와 검증기가 브라우저에서 실행됩니다.

OpenAPI 검증기 사용 방법

1단계: Spec 붙여넣기

도구를 먼저 확인하고 싶다면 텍스트 영역 우측 상단의 "Load Example" 버튼을 클릭하세요.

2단계: Validate Spec 클릭

텍스트 영역 아래의 "Validate Spec" 버튼을 클릭합니다. 파서 실행 중 버튼에 "Validating..."이 표시됩니다.

3단계: 검증 결과 확인

결과 패널이 두 제목 중 하나와 함께 나타납니다:

"✓ Valid OpenAPI Specification"(녹색) — spec이 구조 검증을 통과했습니다.
"✗ Validation Failed"(빨간색) — spec에 수정이 필요한 구조 오류가 있습니다.

4단계: 요약 타일 읽기 (유효한 Spec)

검증을 통과한 spec에 네 개의 요약 타일이 표시됩니다:

Title — info.title의 값
Version — info.version의 값
Paths — 경로 항목의 총 수
Operations — HTTP 메서드+경로 조합의 총 수

5단계: 경고 처리

유효한 spec에서도 세 가지 경고 유형이 표시됩니다:

누락된 info.description — spec에 전체적인 API 설명이 없습니다.
description 또는 summary가 없는 작업 — 카운트로 보고됩니다.
operationId가 없는 작업 — SDK 생성기가 생성된 메서드 이름에 operationId를 사용합니다.

실용적인 예시

예시 1: 누락된 필수 필드 찾기

존재하지 않는 스키마 정의를 가리키는 $ref를 참조하는 Swagger 2.0 spec을 붙여넣으면:

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

예시 2: 품질 경고가 있는 유효한 Spec

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

예시 3: 대규모 Spec 한눈에 확인

500개 경로의 내부 API spec을 붙여넣으면 요약 타일에 "Paths: 147"과 "Operations: 312"가 표시됩니다.

팁과 모범 사례

모든 구조 변경 후 검증하세요. 새 경로 추가, $ref 변경, 스키마 수정은 오류를 도입할 수 있습니다. 검증은 2초 미만입니다.

operationId 경고를 SDK 워크플로우의 차단 요인으로 취급하세요. 설정하지 않으면 생성된 메서드 이름이 경로에서 파생됩니다.

예제를 템플릿으로 사용하세요. 내장 예제는 완전하고 유효한 최소한의 OpenAPI 3.0 spec입니다.

목록 위에서 아래로 오류를 수정하세요. 하나의 스키마 정의 누락이 spec 전체에 연쇄 $ref 오류를 일으킬 수 있습니다.

일반적인 문제 및 문제 해결

"Parse error: ..." — 입력이 유효한 JSON도 YAML도 아닙니다. 일반적인 원인: JSON의 후행 쉼표, 일관되지 않은 YAML 들여쓰기, YAML 들여쓰기의 탭 문자.

Swagger UI가 수용하는 spec에서 검증이 실패함. Swagger UI는 오류에 관대합니다. 이 검증기는 엄격한 스키마 검증을 적용합니다.

설명 추가 후에도 경고가 표시됨. info 내부에 description을 추가했는지 확인하세요.

첫 사용 시 도구가 느림. 라이브러리가 첫 검증 클릭 시 동적으로 로드됩니다.

개인정보 보호 및 보안

자주 묻는 질문

OpenAPI 검증기는 무료인가요? 네. 비용, 계정, 사용 제한이 없습니다.

어떤 OpenAPI 버전이 지원되나요? Swagger 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x.

YAML을 붙여넣을 수 있나요? 두 형식 모두 작동합니다.

도구가 실제 API 엔드포인트를 검증하나요? 아니요. spec 파일이 구조적으로 올바른지만 확인합니다.

Swagger UI에서 작동하는데 여기서 실패하는 이유는? Swagger UI는 오류에 관대하게 spec을 렌더링합니다. 이 검증기는 엄격한 스키마 검증을 적용합니다.

경고에 오탐이 있나요? 세 가지 경고 검사는 보수적입니다. info.description 검사는 필드가 없거나 비어 있을 때만 트리거됩니다.

붙여넣기 대신 spec 파일을 검증할 수 있나요? 도구는 붙여넣은 텍스트만 수용합니다. 파일 업로드 버튼이 없습니다.

이력 패널이 spec 내용을 저장하나요? 네. 브라우저의 IndexedDB 이력에 로컬로 저장됩니다.

빈 spec을 붙여넣으면 어떻게 되나요? 텍스트 영역이 비어 있으면 Validate 버튼이 비활성화됩니다.

OpenAPI 검증기: API Spec 린트

OpenAPI 검증기란?

주요 기능

OpenAPI 검증기 사용 방법

1단계: Spec 붙여넣기

2단계: Validate Spec 클릭

3단계: 검증 결과 확인

4단계: 요약 타일 읽기 (유효한 Spec)

5단계: 경고 처리

실용적인 예시

예시 1: 누락된 필수 필드 찾기

예시 2: 품질 경고가 있는 유효한 Spec

예시 3: 대규모 Spec 한눈에 확인

팁과 모범 사례

일반적인 문제 및 문제 해결

개인정보 보호 및 보안

자주 묻는 질문

관련 도구

계속 읽기

OpenAPI 검증기: API Spec 린트

OpenAPI 검증기란?

주요 기능

OpenAPI 검증기 사용 방법

1단계: Spec 붙여넣기

2단계: Validate Spec 클릭

3단계: 검증 결과 확인

4단계: 요약 타일 읽기 (유효한 Spec)

5단계: 경고 처리

실용적인 예시

예시 1: 누락된 필수 필드 찾기

예시 2: 품질 경고가 있는 유효한 Spec

예시 3: 대규모 Spec 한눈에 확인

팁과 모범 사례

일반적인 문제 및 문제 해결

개인정보 보호 및 보안

자주 묻는 질문

관련 도구

계속 읽기