OpenAPI 3.1 검증기
OpenAPI 3.1 문서를 JSON 또는 YAML로 붙여 넣으면 최상위 구조를 확인할 수 있습니다. 이 도구는 openapi 필드, title과 version을 포함한 info 객체, paths 객체를 확인합니다. 구조 검사이므로 3.1 스키마 키워드는 검증하지 않으며, 3.1에 맞는 일부 패턴은 경고나 오류로 표시될 수 있으니 미리 알아 두시기 바랍니다.
3.1 문서를 확인하는 방법
-
1
3.1 명세 붙여 넣기
`openapi: 3.1.0`(또는 다른 3.1.x 값)이 포함된 문서를 JSON 또는 YAML 형식 그대로 입력란에 붙여 넣으세요.
-
2
검사 실행
결과 단계로 넘어가면 오류와 경고를 확인할 수 있습니다.
-
3
3.1 참고 사항 읽기
표시된 항목이 실제 실수인지, 아래에 설명된 3.1 패턴인지 확인하세요.
-
4
전체 린터로 마무리
구조가 정리되면 JSON Schema 2020-12 규칙을 검사하는 완전한 검증기를 사용하세요.
이 도구가 3.1 파일을 처리하는 방식
3.1 버전은 스키마를 JSON Schema 2020-12에 맞춥니다. 이 검증기는 스키마 내부를 전혀 읽지 않습니다. 최상위 구조와 경로 항목만 살펴봅니다. 따라서 타입 배열이나 const 같은 3.1 스키마 기능은 여기서 통과하거나 실패하지 않습니다. openapi 필드의 값 자체도 검사하지 않으며, openapi 필드가 있기만 하면 존재하는 것으로 간주합니다.
주의해야 할 3.1 패턴 두 가지
| 3.1 파일의 패턴 | 도구가 보고하는 내용 |
|---|---|
webhooks 객체가 있고 paths 객체가 없음 |
오류: Missing ‘paths’ object. |
경로 아래의 trace 작업 |
경고: Unknown method ‘trace’ on the path |
경로 항목의 키로 $ref 사용 |
경고: Unknown method ‘$ref’ on the path |
OpenAPI 3.1에서는 webhooks만 기술하고 paths를 생략할 수 있습니다. 이 도구는 paths를 필수로 요구하므로, 명세상 허용되는 파일이라도 오류로 보고됩니다. 빈 paths: {} 객체를 추가하면 검사를 통과합니다.
여기서 사용하는 메서드 목록은 get, post, put, patch, delete, head, options와 parameters, summary, description, servers입니다. trace 메서드는 명세에 존재하지만 이 목록에는 없으므로, 의도한 것이라면 무시해도 되는 경고가 표시됩니다. 경고가 있어도 문서가 유효하지 않게 되지는 않습니다.
예제
openapi: 3.1.0
info:
title: Events API
version: 2.0.0
webhooks:
newEvent:
post:
summary: Event delivered
결과: 오류 1건, “Missing ‘paths’ object.“입니다. paths: {}를 추가하면 구조 검사를 통과합니다.
이 도구를 언제 쓰고, 언제 더 나아갈지
3.1 파일을 풀 리퀘스트에 올리거나 파트너와 공유하기 전에, 이 페이지로 파일 구조가 올바른지 확인하세요. 검사는 빠르고 메시지는 명확합니다. 구조가 맞으면 3.1 스키마 규칙은 여전히 완전한 린터로 확인해야 합니다. 대부분의 실제 실수가 거기에 숨어 있기 때문입니다. 예를 들어 잘못된 타입 선언, 깨진 참조, 누락된 응답 정의가 있습니다. 두 단계는 대체 관계가 아니라 서로 보완하는 관계로 생각하세요.
의도한 경고라면(예: trace) 검토자가 궁금해하지 않도록 풀 리퀘스트에 적어 두세요. 경고는 유효 결과를 바꾸지 않으므로 그대로 두어도 안전합니다. 파일을 공유하기 전에 해결해야 할 것은 오류입니다.
자주 묻는 질문
아니요. 스키마 객체 내부를 보지 않으므로 JSON Schema 2020-12 키워드는 검사되지 않습니다. 최상위 구조와 경로 항목만 다룹니다.
이 검사는 paths 객체를 요구합니다. webhooks만 있는 3.1 파일에는 paths가 없으므로 paths 누락 오류가 보고됩니다. 빈 paths: {}를 추가하면 통과합니다.
아니요. 도구는 openapi 또는 swagger 필드가 있는지만 확인하고 값은 확인하지 않습니다.
꼭 그렇지는 않습니다. trace는 명세에서 유효한 작업입니다. 도구가 알려진 메서드 목록에 포함하지 않았을 뿐입니다.
관련 도구
보색 찾기
어떤 입력에 대해서도 보색을 찾습니다. HSL 반대 색, 분할 보색 쌍, 그리고 접근성 있는 조합 제안을 반환합니다.
Webpack 설정 생성기
순수 JavaScript, React, Vue용 webpack 5 webpack.config.js를 만드세요. TypeScript, Babel, CSS 또는 Sass, 이미지, HtmlWebpackPlugin, 개발 서버, npm install 명령까지 함께 제공합니다.
Protocol Buffers 디코더
hex, Base64, Base64URL, 텍스트 또는 파일의 Protobuf 와이어 형식 바이트를 브라우저에서 디코딩하고 정확한 필드 후보를 확인한 뒤 비공개 보고서로 내보냅니다.
XML 포매터
일관된 들여쓰기로 XML 문서를 정렬 출력하고, 정확한 줄 번호로 적격성 오류를 잡아냅니다.
XSD 검증기
XML 문서를 XSD 스키마에 대해 검증하고, 요소와 타입 불일치를 정확한 줄 번호와 함께 보고합니다.
색상 혼합기
두 HEX 색상을 2-20개의 균등한 색상 견본으로 섞습니다. 양 끝 색상을 포함해 각 중간 색상을 대문자 HEX 코드로 확인하세요.
이 도구는 다른 언어로도 제공됩니다
- ตัวตรวจสอบ OpenAPI 3.1 [TH]
- Walidator OpenAPI 3.1 [PL]
- Công cụ kiểm tra OpenAPI 3.1 [VI]
- Validator OpenAPI 3.1 [ID]
- مدقق OpenAPI 3.1 [AR]
- OpenAPI 3.1 Validator [DE]
- OpenAPI 3.1 バリデーター [JA]
- Validador OpenAPI 3.1 [PT]
- Validador de OpenAPI 3.1 [ES]
- OpenAPI 3.1-validerare [SV]
- Validateur OpenAPI 3.1 [FR]
- OpenAPI 3.1 Validator [NL]
- OpenAPI 3.1 Validator [EN]
- Validatore OpenAPI 3.1 [IT]
- Валидатор OpenAPI 3.1 [RU]
- OpenAPI 3.1 Doğrulayıcı [TR]
- OpenAPI 3.1 验证器 [ZH]