OpenAPI 데이터 모델

OpenAPI 데이터 모델 (Schemas)

REST API를 기술할 때 데이터의 모양을 정확히 정의하는 건 문서 그 이상의 의미가 있어요. OpenAPI의 데이터 타입은 JSON Schema(Wright Draft 00, 일명 Draft 5)의 확장 부분집합에 기반하고, Schema 객체로 기술돼요.

출처: https://swagger.io/docs/specification/data-models/

가장 흔한 object 타입의 예시를 볼게요.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      required:
        - id
        - name

데이터 모델링에서 다루는 주제는 다양해요.

  • 데이터 타입: string, number, integer, boolean, array, object 같은 기본 타입과 format(예: int64, date-time, uuid)으로 세부 표현을 다듬어요.
  • Enum: 허용 값 집합을 정의해요. enum: [user, poweruser, admin]처럼요.
  • 딕셔너리/해시맵: 키-값 구조를 additionalProperties로 표현해요.
  • oneOf / anyOf / allOf / not: 타입을 조합해 상속·폴리모피즘 같은 복잡한 관계를 나타내요. 예를 들어 oneOf: [Cat, Dog]는 "둘 중 하나"라는 뜻이에요.
  • XML 표현: xml 키워드로 XML로 직렬화될 때의 형태를 지정해요.
  • JSON Schema 키워드: minimum, maxLength, pattern, required 등 JSON Schema가 지원하는 검증 키워드를 쓸 수 있어요.

이 스키마들은 components.schemas에 정의해 두고, 경로·파라미터·응답에서 $ref로 참조하는 게 일반적이에요. 한 번 정의한 모델을 여기저기서 재사용하면서, API 전체의 데이터 계약이 일관되게 유지되죠.

더 알아보기