이전 글 "API에 여러 파라미터 구조가 있을 때 대처 방법"에서, API에 여러 파라미터 구조가 필요할 때, Apidog에서 oneOf, anyOf, allOf를 사용하여 정의할 수 있다고 설명했습니다.
이러한 스키마 구성 요소를 사용하여 파라미터 구조를 설정하고, 파라미터에 데이터 유형을 식별하는 필드가 포함되어 있다면, OpenAPI 사양의 discriminator 기능을 사용하여 스키마를 더욱 직관적으로 구별함으로써 문서를 훨씬 명확하게 만들 수 있습니다.
Discriminator란 무엇인가요?
OpenAPI에서 discriminator의 역할은 객체 지향 프로그래밍의 "다형성"을 구현하는 것입니다.
간단히 말해, 공유된 속성과 그 고유한 값을 사용하여 oneOf 또는 anyOf 목록에서 어떤 특정 스키마를 사용해야 하는지 명확하게 나타냅니다.
예를 들어, 반려동물 상점에서 반려동물을 설명하기 위한 스키마를 사용해야 합니다. (그리고 고양이와 개는 서로 다른 속성을 가집니다.)
개에 대한 스키마는 다음과 같습니다:
{
"name": "Hotdog",
"age": 3,
"weight": 25.5,
"petType": "dog",
"breed": "Golden Retriever",
"isVaccinated": true,
"walkingSchedule": "Morning and Evening",
"favoriteToys": ["Frisbee", "Tennis Ball"],
"trainingLevel": "Intermediate"
}고양이에 대한 스키마는 다음과 같습니다:
{
"name": "Meow",
"age": 2,
"weight": 4.2,
"petType": "cat",
"isVaccinated": true,
"isIndoor": true,
"litterBoxType": "Enclosed",
"scratchingPostHeight": 120,
"favoriteSleepingSpot": "Balcony"
}보시다시피, 두 스키마 모두 petType, name, age 등과 같은 공통 필드를 가지고 있지만, 개는 breed, walkingSchedule 등과 같은 특정 필드를 가지고 있고, 고양이는 isIndoor, litterBoxType 등과 같은 특정 필드를 가지고 있습니다.
API 문서를 설계할 때 oneOf만 사용하여 이러한 스키마를 정의한다면, 문서는 기술적으로 dog와 cat 스키마를 구별할 수 있습니다. 하지만 각 유형의 대응 관계가 명확하지 않습니다. 독자는 두 스키마 탭을 오가며 비교해야 하는데, 파라미터가 많아지면 혼란스러워질 수 있습니다.
discriminator를 추가하면 문서에 드롭다운 메뉴가 표시되어, 독자가 petType 값(dog 또는 cat)을 선택할 수 있습니다. 선택하면 페이지는 관련 필드와 함께 올바른 스키마를 자동으로 표시합니다. 이렇게 하면 여러 탭을 비교할 필요가 없어지고 각 스키마 간의 차이점이 훨씬 명확해집니다.
discriminator는 일반적으로 oneOf 또는 anyOf와 함께 사용됩니다. oneOf는 가능한 객체 스키마를 정의하고, discriminator는 선택된 유형에 따라 어떤 스키마를 적용할지 파서에게 알려줍니다.
이를 통해 복잡한 객체가 더 명확해지고, 문서를 렌더링하거나 코드를 생성할 때 도구가 유형을 자동으로 구별하는 데 도움이 됩니다.
discriminator의 구성 속성
discriminator는 두 가지 주요 속성을 포함합니다:
- propertyName: 위 예시의
petType과 같이 유형을 구별하는 데 사용되는 필드 이름을 지정합니다. - mapping: 필드 값과 특정 스키마 간의 매핑 관계를 정의합니다. 예를 들어,
"dog"는 개 스키마에,"cat"는 고양이 스키마에 해당합니다.
OpenAPI에서의 구성 예시:
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'Apidog에서 Discriminator 구성하기
Apidog는 discriminator를 두 가지 방법으로 구성하는 것을 지원합니다:
- GUI + JSON 스키마
- OpenAPI 사양을 직접 가져오기
방법 1: GUI + JSON 스키마
먼저, Apidog에서 스키마를 생성합니다. 예를 들어, Dog와 Cat:
이 스키마를 사용하려는 엔드포인트를 열고 요청 또는 응답 본문 편집기로 이동합니다.
스키마 구성으로 정의하려는 필드를 선택하고 고급 설정 → 스키마 구성 → oneOf를 선택합니다.
oneOf에서 Dog와 Cat과 같이 필요한 스키마를 참조합니다.
이제 oneOf를 통해 여러 가능한 스키마를 정의했습니다. 다음으로, 이 스키마들을 구별하는 방법을 지정하기 위해 discriminator를 추가해야 합니다. 코드 모드로 전환하려면 JSON Schema를 클릭하세요:
discriminator 구성을 적절한 위치(oneOf와 동일한 레벨)에 추가합니다. 예를 들어:
"discriminator": {
"propertyName": "petType",
"mapping": {
"dog": "#/definitions/190704823",
"cat": "#/definitions/190704706"
}
}mapping의 값(예: #/definitions/190704823)은 Apidog가 스키마에 대해 내부적으로 생성하는 고유 ID입니다. 각 스키마에 해당하는 definitions 경로는 JSON 스키마 구성 패널에서 찾을 수 있습니다.
구성이 완료되면 저장합니다. API 문서에서 petType 필드의 값에 따라 객체 유형을 지능적으로 전환할 수 있습니다.
방법 2: OpenAPI 사양 직접 가져오기
이는 "디자인 우선(design-first)" 워크플로에 익숙한 팀에 특히 적합한 보다 표준적인 접근 방식입니다.
discriminator가 포함된 OpenAPI 사양을 작성한 다음 Apidog로 가져옵니다.
예를 들어, OpenAPI 사양에서 discriminator의 정의는 다음과 같습니다:
Pet:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'이 정의는 다음을 명확히 명시합니다:
oneOf를 통해 객체가Dog또는Cat유형일 수 있음을 지정합니다.discriminator를 통해petType필드의 값에 따라 특정 유형을 결정하도록 지정합니다.mapping을 통해"dog"가Dog스키마에,"cat"가Cat스키마에 해당함을 명확히 지정합니다.
전체 OpenAPI 사양은 다음과 같습니다:
openapi: 3.0.3
info:
title: Pet Shop API
version: 1.0.0
components:
schemas:
Dog:
type: object
properties:
petType:
type: string
enum: [dog]
name:
type: string
age:
type: integer
weight:
type: number
breed:
type: string
isVaccinated:
type: boolean
walkingSchedule:
type: string
favoriteToys:
type: array
items:
type: string
trainingLevel:
type: string
required:
- petType
- name
- age
Cat:
type: object
properties:
petType:
type: string
enum: [cat]
name:
type: string
age:
type: integer
weight:
type: number
isVaccinated:
type: boolean
isIndoor:
type: boolean
litterBoxType:
type: string
scratchingPostHeight:
type: integer
favoriteSleepingSpot:
type: string
required:
- petType
- name
- age
Pet:
oneOf:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Cat'
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'
paths:
/pets:
get:
summary: Get pet information
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'OpenAPI 사양 작성을 완료한 후 Apidog의 가져오기 기능을 사용합니다. Apidog는 모든 사양을 파싱하여 해당 스키마와 엔드포인트를 자동으로 생성하고, discriminator 구성을 올바르게 인식합니다 (여기서는 파라미터 값을 고정하기 위해 enum이 추가되었습니다).
자주 묻는 질문
1. Discriminator는 언제 사용해야 하나요?
discriminator는 엔드포인트에 이미 스키마를 식별하는 필드가 포함되어 있을 때만 사용해야 합니다. 위 예시에서 petType 필드는 API 설계에 존재하며 반려동물 유형을 구별하는 데 사용됩니다.
discriminator는 해당 필드의 값에 따라 올바른 스키마를 선택하는 방법을 도구에 알려줄 뿐입니다.
만약 엔드포인트에 그러한 유형 식별 필드가 포함되어 있지 않다면, discriminator는 적절하지 않으며 oneOf만 사용하는 것으로 충분합니다.
또한, 스키마가 단순하거나 몇 가지 변형만 있는 경우 discriminator가 전혀 필요하지 않을 수도 있습니다.
2. Discriminator는 oneOf와 함께 사용해야만 하나요?
네. discriminator는 oneOf, anyOf, allOf와 함께 사용되어야 합니다. 그 자체로는 스키마를 정의할 수 없으며, 여러 가능한 스키마를 구별하는 방법을 설명할 뿐입니다.
결론
discriminator는 oneOf/anyOf/allOf의 사용자 경험을 향상시키기 위해 사용되는 OpenAPI 사양의 선택적 기능입니다.
엔드포인트 사양에 이미 유형을 식별하는 데 사용되는 필드가 포함되어 있을 때, Apidog에서 discriminator를 구성하여 API 문서를 더 명확하고 지능적으로 만들 수 있습니다.
물론, 구성이 번거롭거나 스키마가 비교적 단순하다고 생각되면, oneOf와 같은 스키마 구성만 완전히 사용할 수도 있습니다.