OpenAPI Specification의 JSON vs YAML 형식 차이 비교

8월 05, 2025

 

OpenAPI Specification, 줄여서 OAS는 REST API를 표준화된 방식으로 설명하기 위한 명세입니다. OpenAPI 문서는 JSON 또는 YAML 형식으로 작성할 수 있으며, 두 형식은 같은 OpenAPI 구조와 의미를 표현할 수 있습니다.

즉, JSON으로 작성하든 YAML로 작성하든 OpenAPI 문서가 담는 API 정보 자체는 동일합니다. 차이는 주로 사람이 읽고 작성하기 쉬운지, 도구와 자동화 환경에서 다루기 쉬운지, 문법적으로 얼마나 엄격한지에 있습니다.

핵심 요약

구분 JSON YAML
기본 특징 데이터 교환에 널리 쓰이는 엄격한 텍스트 형식 사람이 읽고 쓰기 쉽도록 설계된 데이터 직렬화 형식
OpenAPI 지원 여부 공식 지원 공식 지원
가독성 중괄호, 대괄호, 쉼표가 많아 길어질 수 있음 들여쓰기 기반이라 구조를 한눈에 보기 쉬움
주석 표준 JSON에서는 주석 불가 #로 주석 작성 가능
문법 엄격성 쉼표, 따옴표, 중괄호 규칙이 엄격함 들여쓰기와 공백 처리에 주의 필요
도구 호환성 대부분의 언어와 도구에서 기본 지원이 강함 OpenAPI 도구에서는 널리 지원되지만, 일반 프로그래밍 환경에서는 별도 YAML 파서가 필요할 수 있음
파일 크기 보기 좋게 작성하면 다소 길어질 수 있음 작성 방식에 따라 더 간결한 경우가 많음
실무 선호도 자동화, 변환, 시스템 간 교환에 적합 문서 작성, 리뷰, 협업에 적합

OpenAPI에서 JSON과 YAML은 무엇이 다른가?

OpenAPI 문서는 API의 엔드포인트, 요청 파라미터, 응답 구조, 인증 방식, 스키마 등을 정의합니다. 이 정보는 JSON으로도 표현할 수 있고 YAML로도 표현할 수 있습니다.

예를 들어 다음 두 문서는 같은 의미를 가집니다.

JSON 예시

{
  "openapi": "3.1.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
}

YAML 예시

openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users
      responses:
        '200':
          description: Successful response

두 문서는 표현 방식만 다를 뿐, OpenAPI 관점에서는 같은 API 설명입니다.

JSON의 장점

JSON은 구조가 명확하고 문법이 엄격합니다. 대부분의 프로그래밍 언어에서 기본적으로 JSON 파싱 기능을 제공하거나 매우 안정적인 라이브러리를 제공합니다.

따라서 다음과 같은 경우 JSON이 적합합니다.

  • API 명세를 시스템 간에 자동으로 주고받는 경우
  • CI/CD, 코드 생성, 테스트 자동화 등 기계 처리 중심의 환경
  • JSON 기반 도구 체인과 직접 연동해야 하는 경우
  • 파서 간 차이를 최소화하고 싶은 경우

다만 JSON은 주석을 지원하지 않으며, 큰 OpenAPI 문서를 사람이 직접 읽거나 수정할 때는 중괄호, 쉼표, 따옴표 때문에 가독성이 떨어질 수 있습니다.

YAML의 장점

YAML은 들여쓰기 기반 문법을 사용하기 때문에 사람이 읽고 작성하기 쉽습니다. OpenAPI 예제나 문서에서 YAML이 자주 사용되는 이유도 이 때문입니다.

YAML은 다음과 같은 경우에 적합합니다.

  • 사람이 직접 OpenAPI 문서를 작성하고 관리하는 경우
  • 팀원들이 API 명세를 리뷰해야 하는 경우
  • 문서 안에 설명용 주석을 남기고 싶은 경우
  • Swagger Editor, Redocly, Stoplight 등 OpenAPI 문서 도구에서 명세를 관리하는 경우

다만 YAML은 들여쓰기와 공백에 민감합니다. 탭과 스페이스 혼용, 잘못된 들여쓰기, 문자열 자동 해석 등으로 인해 예상치 못한 오류가 발생할 수 있습니다.

예를 들어 YAML에서는 다음처럼 주석을 남길 수 있습니다.

openapi: 3.1.0

info:
  title: Sample API # API 이름
  version: 1.0.0

paths:
  /users:
    get:
      summary: Get users
      responses:
        '200':
          description: Successful response

주의할 점: YAML이 더 많은 타입을 지원한다는 표현

YAML은 JSON보다 문법적으로 더 다양한 표현을 지원합니다. 예를 들어 주석, 앵커, 별칭, 여러 줄 문자열 같은 기능이 있습니다.

하지만 OpenAPI 문서에서는 가능한 한 JSON과 호환되는 형태로 작성하는 것이 안전합니다. OpenAPI 문서는 본질적으로 JSON 객체로 해석되기 때문입니다.

따라서 YAML에서만 가능한 특수한 표현을 과도하게 사용하면 도구나 파서에 따라 호환성 문제가 생길 수 있습니다. 실무에서는 YAML을 사용하더라도 다음처럼 JSON과 자연스럽게 변환 가능한 형태로 작성하는 것이 좋습니다.

title: Sample API
version: 1.0.0
enabled: true
tags:
  - users
  - admin

파일 크기 차이는 절대적인 기준이 아니다

흔히 YAML이 JSON보다 파일 크기가 작다고 말하지만, 항상 그런 것은 아닙니다.

YAML은 중괄호와 따옴표가 적어 사람이 작성한 문서에서는 더 간결해 보이는 경우가 많습니다. 하지만 JSON도 공백과 줄바꿈을 제거해 minify하면 매우 작아질 수 있습니다.

따라서 파일 크기만으로 JSON과 YAML을 선택하기보다는, 다음 기준을 우선 고려하는 것이 좋습니다.

  • 사람이 자주 읽고 수정하는가?
  • 자동화 시스템이 주로 처리하는가?
  • 사용하는 도구가 어떤 형식을 더 안정적으로 지원하는가?
  • 팀에서 어떤 형식에 더 익숙한가?

실무에서는 어떤 형식을 선택해야 할까?

YAML을 추천하는 경우

YAML은 사람이 읽고 관리하기 쉬우므로 OpenAPI 문서를 직접 작성하거나 리뷰하는 환경에 적합합니다.

특히 다음과 같은 경우 YAML이 좋습니다.

  • API 명세를 Git에서 리뷰한다
  • 문서에 설명용 주석을 남기고 싶다
  • Swagger Editor 같은 도구에서 직접 수정한다
  • 개발자와 기획자, QA가 함께 API 문서를 확인한다

JSON을 추천하는 경우

JSON은 도구와 시스템 간 데이터 교환에 강합니다. 자동화나 프로그램 처리 중심의 환경에서는 JSON이 더 적합할 수 있습니다.

특히 다음과 같은 경우 JSON이 좋습니다.

  • 코드 생성기나 테스트 자동화 도구가 JSON을 기준으로 동작한다
  • API 명세를 다른 시스템에 전달해야 한다
  • 파서 호환성을 최대한 단순하게 유지하고 싶다
  • 사람이 직접 편집하기보다 프로그램이 생성하는 문서다

결론

OpenAPI Specification은 JSON과 YAML을 모두 공식적으로 지원합니다. 두 형식은 같은 API 정보를 표현할 수 있으며, OpenAPI 문서의 기능이나 의미가 달라지는 것은 아닙니다.

정리하면 다음과 같습니다.

  • 사람이 읽고 작성하기 쉬운 문서가 필요하다면 YAML이 유리합니다.
  • 자동화, 시스템 연동, 엄격한 파싱이 중요하다면 JSON이 유리합니다.
  • OpenAPI 문서의 의미는 JSON과 YAML 중 어떤 형식을 선택해도 동일합니다.
  • YAML을 사용하더라도 JSON으로 변환 가능한 구조를 유지하는 것이 안전합니다.

실무에서는 보통 YAML로 작성하고, 필요할 때 JSON으로 변환해 자동화 도구에 전달하는 방식을 많이 사용합니다. 팀의 작업 방식과 도구 환경에 맞춰 선택하면 됩니다.

참고 자료

댓글 쓰기 · 수정

0 댓글