OpenAPI 점검
OpenAPI Linter
OpenAPI 문서에서 누락된 응답, 쓰이지 않는 스키마, 아무것도 가리키지 않는 참조처럼 코드 생성기를 깨뜨리는 결함을 점검합니다.
OpenAPI 3.0·3.1 문서를 점검합니다. 코드 생성기를 걸려 넘어지게 하는 것, 클라이언트 라이브러리가 거짓말하게 만드는 것, 규격이 요구하는 것을 봅니다. 규칙은 직접 쓴 것이고 페이지에 전부 나열돼 있습니다. 취향이 아니라 문제만 봅니다.
OpenAPI 문서
openapi.yaml 놓기
이 탭 안에서만 읽습니다.
점검 결과 24건
오류schema-array-itemscomponents.schemas.Order.items
`type: array`인데 `items`가 없습니다.
오류path-param-undeclaredGET /orders/{orderId}
경로의 `{orderId}` 자리가 파라미터로 선언되지 않았습니다.
오류response-descriptionGET /orders/{orderId}
`200` 응답에 description이 없습니다.
오류schema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array`인데 `items`가 없습니다.
오류info-missinginfo
`info.version`이 없습니다. OpenAPI의 버전이 아니라 이 API의 버전입니다.
오류operation-id-duplicatePOST /orders/{orderId}
operationId `getOrder` 값이 GET /orders/{orderId}에도 있습니다.
오류path-param-requiredPOST /orders/{orderId}
`in: path` 파라미터 `id`에 `required: true`가 없습니다.
오류path-param-undeclaredPOST /orders/{orderId}
경로의 `{orderId}` 자리가 파라미터로 선언되지 않았습니다.
오류path-param-unusedPOST /orders/{orderId}
`in: path`의 `id` 파라미터가 경로에 없습니다.
경고path-trailing-slash/orders/
이 경로가 `/`로 끝납니다.
경고schema-unusedcomponents.schemas.Customer
이 스키마를 참조하는 곳이 없습니다.
경고operation-id-missingGET /orders/
operationId가 없습니다.
경고response-errorGET /orders/
4xx 응답이 없습니다.
경고description-missingGET /orders/{orderId}
summary도 description도 없습니다.
경고response-errorGET /orders/{orderId}
4xx 응답이 없습니다.
경고description-missingPOST /orders/{orderId}
summary도 description도 없습니다.
경고response-errorPOST /orders/{orderId}
4xx 응답이 없습니다.
경고response-successPOST /orders/{orderId}
2xx나 3xx 응답이 없습니다.
참고tag-missingGET /orders/
태그가 없습니다.
참고tag-missingGET /orders/{orderId}
태그가 없습니다.
참고parameter-descriptionPOST /orders/{orderId}
파라미터 `id`에 description이 없습니다.
참고response-default-onlyPOST /orders/{orderId}
응답이 `default` 하나뿐입니다.
참고tag-missingPOST /orders/{orderId}
태그가 없습니다.
참고servers-missingservers
서버가 하나도 없어서 기준 주소가 `/`가 됩니다.
OpenAPI
3.0.3
작업
3
오류
9
경고
9
참고
6
직접 정한 규칙입니다. 코드 생성기가 걸려 넘어지는 것, 클라이언트 라이브러리가 거짓말하게 되는 것, 규격이 필수라고 한 것 — 취향이 아니라 문제를 잡습니다. Spectral의 규칙 세트를 읽어들이지는 않습니다.
두 버전의 차이를 보려면 OpenAPI 변경 비교를 쓰세요.
사용 방법
문서를 붙여넣습니다
JSON이든 YAML이든, 3.0이든 3.1이든 됩니다. 이 탭에서 파싱하고 아무것도 올리지 않습니다.
오류부터 처리합니다
결과마다 규칙 id와 문서 안의 정확한 위치가 붙습니다. 오류는 실제로 잘못될 것들이고, 경고는 대개 잘못되는 것들입니다.
뜻밖의 결과가 나오면 규칙 목록을 봅니다
규칙마다 심각도와 존재 이유가 적혀 있습니다. 동의하지 않는 결과라도 최소한 읽을 수 있는 근거가 있습니다.
자주 묻는 질문
Spectral 규칙 세트를 불러올 수 있나요?
아니요. 고정된 규칙 세트를 직접 썼고, 사내 스타일이 아니라 문제를 기준으로 골랐습니다. Spectral 설정이 있다면 그것을 존중하는 도구는 Spectral입니다.
Swagger 2.0 파일을 안 읽습니다.
맞습니다. 2.0은 조금 오래된 3.0이 아니라 문서 구조 자체가 다르고, 규칙의 절반은 적용되지 않습니다. 먼저 변환하세요. 보통 `swagger2openapi`를 씁니다.
외부 `$ref`를 따라가지 않았습니다.
문서 안의 `$ref`는 풉니다. 다른 파일을 가리키는 것은 사용자의 기계에만 있는 경로에서 가져와야 합니다. 검사가 깨끗한 것이 아니라 불완전했다는 것을 알 수 있도록 참고로 표시합니다.
`operationId`가 없으면 왜 경고인가요?
생성기가 그 작업에 대해 만들 함수 이름을 그것으로 짓기 때문입니다. 없으면 경로와 메서드에서 이름을 만들어 내는데, 경로가 바뀌는 순간 그 이름도 바뀝니다. API의 이름 변경 하나가 모든 클라이언트의 이름 변경이 됩니다.
이 도구로 이어지는 것
JSON 스키마 생성
JSON to JSON Schema
하나 또는 여러 예시에서 JSON 스키마를 추론하고 발견한 형태를 합칩니다.
JSON 스키마 검증
JSON Schema Validator
문서를 JSON 스키마로 검증하고 실패한 위치를 경로와 함께 보여 줍니다.
curl 코드 변환
curl to Code
curl 명령을 fetch·axios·파이썬 requests·Go·PHP·PowerShell 코드로 변환합니다.
OpenAPI 변경 비교
OpenAPI Diff
두 OpenAPI 문서를 비교해 호환성을 깨는 변경과 추가만 된 변경을 구분해 보여 줍니다.
다음 단계
이 도구의 결과를 그대로 받을 수 있는 도구들입니다.
curl 코드 변환
curl to Code
curl 명령을 fetch·axios·파이썬 requests·Go·PHP·PowerShell 코드로 변환합니다.
JSON 스키마 검증
JSON Schema Validator
문서를 JSON 스키마로 검증하고 실패한 위치를 경로와 함께 보여 줍니다.
OpenAPI 변경 비교
OpenAPI Diff
두 OpenAPI 문서를 비교해 호환성을 깨는 변경과 추가만 된 변경을 구분해 보여 줍니다.
YAML 정렬·검사
YAML Formatter & Validator
YAML 들여쓰기를 통일하고 문법을 검사하며, 파서를 깨뜨리는 탭·앵커 실수를 표시합니다.
JSON CSV 변환
JSON ⇄ CSV
중첩 JSON을 점 표기 열 이름으로 펼치거나, 표에서 객체를 다시 만듭니다.
JSON 비교
JSON Diff
키 순서를 무시하고 두 JSON을 구조로 비교해 추가·삭제·변경된 경로를 알려 줍니다.