OpenAPI 포맷터·검사기

OpenAPI 포맷터·검사기 사용 가이드

API 명세는 조금만 어긋나도 문서 화면이 깨지거나 코드 생성기가 실패합니다. 이 도구는 OpenAPI 문서를 YAML 또는 JSON으로 읽어 필수 항목과 자주 틀리는 연결 관계를 확인하고, 마지막에 들여쓰기를 정리한 JSON을 함께 보여 주는 포맷터 역할도 합니다.

openapi 버전과 info.title·info.version을 확인하고, 경로가 /로 시작하는지, 각 작업에 responses가 있고 응답마다 description이 있는지, 상태 코드가 올바른지 봅니다. /tools/{id}처럼 경로에 쓴 매개변수가 in: path, required: true로 선언되었는지와 반대로 선언만 있고 경로에 없는 경우도 찾습니다.

같은 operationId가 두 번 쓰이면 코드 생성 시 함수 이름이 겹치므로 오류로 표시하고, 문서 안의 모든 $ref(#/components/...)가 실제 대상을 가리키는지 확인합니다. 다른 파일을 가리키는 $ref는 '참고'로만 알려 줍니다.

사용 방법

1. 1'OpenAPI 문서' 칸에 openapi.yaml 또는 JSON 내용을 붙여 넣습니다.
2. 2'실행'을 누르면 경로·작업·스키마 개수와 함께 오류·경고·참고가 나오고, 그 아래에 정리된 JSON이 이어집니다.
3. 3지적된 작업(GET /경로 등)을 찾아 고친 뒤 다시 실행합니다.

openapi: 3.0.3
info:
  title: Tool API
  version: '1.0'
paths:
  /tools/{id}:
    get:
      operationId: getTool
      responses:
        '200':
          description: OK

오류 1 · 경고 0 · 참고 0
OpenAPI 3.0.3 · 경로 1개 · 작업 1개 · 스키마 0개

[오류] GET /tools/{id}: 경로 매개변수 {id}가 parameters에 선언되지 않았습니다.

정리된 JSON:
{ … }

이럴 때 쓰면 좋아요

• Swagger UI나 Redoc 화면이 깨지는 원인을 찾을 때
• OpenAPI Generator로 클라이언트 코드를 만들기 전에 명세를 점검할 때
• YAML로 쓴 명세를 JSON으로 바꿔 다른 도구에 넣을 때
• 여러 사람이 고친 명세에서 중복 operationId와 끊긴 $ref를 찾을 때

문제가 생겼을 때

활용 팁

• info.version을 1.0처럼 따옴표 없이 쓰면 숫자로 읽혀 1이 될 수 있습니다. '1.0'처럼 문자열로 쓰세요.
• operationId는 생성되는 함수 이름이 되므로 listTools, getTool처럼 동사로 시작하는 고유한 이름을 쓰면 좋습니다.

자주 묻는 질문