스키마 구축

Schema Editor 활용

Schema Editor는 API가 활용하는 데이터 구조를 설계하고 모델링하는 데 도움을 주는 강력한 도구입니다. 이는 JSON Schema를 기반으로 하며 JSON 또는 XML 데이터 구조를 설계하는 데 사용됩니다.

Schema Editor를 활용하여 다음을 수행할 수 있습니다.

특정 API 엔드포인트에 맞게 조정된 API 요청 및 응답 본문을 개발합니다.

하나 또는 여러 API에서 적용할 수 있는 데이터 모델을 구성합니다.

모든 스키마는 루트 객체로 시작합니다. 스키마를 구축하려면 이 루트 객체에 속성을 추가하십시오.

속성 추가

루트 객체 옆의 +(하위 노드 추가) 기호를 클릭하여 새 속성을 추가하십시오.

속성 이름 지정

속성의 이름(또는 키)을 입력하십시오.

속성 유형 선택

일반적인 데이터 유형을 선택하거나 사전 정의된 스키마에 대한 참조를 선택하십시오.

고급 설정

Type Editor를 활용하여 각 속성에 기본값 및 형식과 같은 데이터 유형을 지정하십시오.

속성 관리

속성을 이동, 복사 또는 삭제하여 재정렬하십시오. 또한 속성에 설명을 추가하고 필수 항목으로 표시할 수도 있습니다.

대체 방법

데이터베이스 테이블 또는 JSON schema 파일에서 가져와 새 스키마를 생성할 수도 있습니다. Generate Schemas from JSON etc.에 대해 자세히 알아보십시오.

속성 유형

JSON Schema 표준에 맞추어, Apidog Schema Editor는 다음 기본 데이터 유형을 지원합니다.

유형	설명
null	JSON "null" 값을 나타냅니다.
boolean	JSON "true" 또는 "false" 값에 해당하는 "true" 또는 "false" 값을 나타냅니다.
object	JSON "object" 값에 해당하는 순서 없는 키-값 쌍의 컬렉션을 나타냅니다.
array	JSON "array" 값에 해당하는 순서 있는 값 목록을 나타냅니다.
number	JSON "number" 값에 해당하는 임의 정밀도의 10진수 값을 나타냅니다.
string	JSON "string" 값에 해당하는 Unicode 문자 문자열을 나타냅니다.

배열 데이터 유형

array 데이터 유형을 사용할 경우, 하위 수준의 ITEMS 속성이 자동으로 생성됩니다. 이는 배열 내 요소의 데이터 유형을 지정합니다.

앞서 언급한 표준 데이터 구조 외에도, Apidog Schema Editor는 다음을 지원합니다.

다른 스키마 참조: API 문서 내 다른 위치에 정의된 스키마를 참조하고 재사용할 수 있습니다.

any: 모든 데이터 유형이 될 수 있는 값을 나타냅니다.

스키마 구성: 여러 스키마를 결합하여 복잡한 데이터 구조를 생성할 수 있습니다.

사용자 지정: 사용자가 특정 요구 사항 및 데이터 모델링 필요에 맞게 스키마를 사용자 지정하고 조정할 수 있습니다.

다른 스키마 참조

"Reference other schemas" 기능을 활용하여 이전에 정의된 스키마를 참조할 수 있습니다.

다른 스키마를 참조한 후에는 Schema Editor에서 참조된 스키마를 확인할 수 있습니다.

참조된 스키마에 대한 주요 사항:

원본 스키마에 적용된 모든 수정 사항은 참조하는 스키마에 반영됩니다.

참조된 스키마는 직접 편집할 수 없습니다. 변경하려면 다음을 수행할 수 있습니다.

스키마 이름을 클릭하여 원본 스키마로 이동한 후 편집합니다.

스키마에서 Dereference를 클릭하면 스키마가 일련의 독립 속성으로 변환되어 개별적으로 편집할 수 있습니다.

특정 속성의 정의를 독립적으로 수정해야 하는 경우, 해당 속성을 Dereference하도록 선택하여 개별 수정을 가능하게 할 수 있습니다. 원본 스키마의 모든 변경 사항은 역참조된 속성에 영향을 주지 않습니다.

엔드포인트에서 참조된 스키마의 모든 속성이 필요하지 않은 경우, Hide를 클릭하여 불필요한 속성을 숨길 수 있습니다.

스키마 구성

데이터 구조의 속성이 여러 가능한 데이터 유형을 가질 수 있는 경우, Schema Composition을 사용하여 여러 스키마를 결합할 수 있습니다.

Apidog는 다음 구성 키워드를 지원합니다.

키워드	설명
allOf (AND)	속성이 구성에 정의된 모든 스키마를 준수해야 함을 지정합니다.
anyOf (OR)	속성이 구성에 나열된 스키마 중 어느 하나를 따를 수 있음을 지정합니다.
oneOf (XOR)	속성이 구성에 정의된 스키마 중 하나, 그리고 단 하나만 준수해야 함을 지정합니다.

Schema Composition을 선택하면 속성 아래에 "0" 및 "1"이라는 하위 속성이 표시되며, 이는 구성 내 각 스키마를 나타냅니다. 각 하위 속성의 스키마 유형을 수정하고 필요에 따라 추가 스키마를 더할 수 있습니다.

API 문서에서 Schema Composition은 다음과 같이 표시됩니다.

OneOf 아래의 두 선택적 객체를 확인할 수 있습니다. 이미지에 표시된 것처럼 이름을 표시하려면 Type editor의 title 필드에 이름을 입력해야 합니다.

사용자 지정

"Customize"를 선택하면 편집기 내에서 JSON Schema를 직접 편집할 수 있습니다.

속성 설정

각 속성에는 데이터 유형 옆에 여러 버튼이 있습니다.

버튼	설명
*	속성이 필수인지 여부를 나타냅니다.
N	속성이 null 값을 허용하는지 여부를 지정합니다.
Settings	Type Editor에서 고급 설정을 편집할 수 있습니다.

Type Editor

Type Editor는 JSON Schema에 맞추어 속성을 시각적으로 설명합니다.

이러한 고급 설정이 구성되면 다음 영역에 적용됩니다.

응답 예시를 추가할 때 설정을 기반으로 자동 생성하도록 클릭할 수 있습니다.

API 문서에 표시됩니다.

요청 본문에서 설정을 기반으로 자동 생성하도록 클릭할 수 있습니다.

요청을 전송하면 반환된 데이터가 설정에 대해 자동으로 검증됩니다.

목 서비스에서 설정을 기반으로 응답 데이터가 생성됩니다.

열거형 속성

String, Integer, Number 유형의 경우 Apidog는 enum을 지원합니다. enum 스위치를 전환하여 enum 값과 설명을 추가할 수 있습니다. 또한 enum 값에 대해 Bulk Edit를 수행할 수 있습니다.

목

속성의 고급 설정 외에도, 목 값을 입력하여 필드의 목 콘텐츠를 지정할 수 있습니다. 목 값은 고급 설정의 설정보다 우선합니다.

목 값은 Faker.js 구문을 지원하므로, 드롭다운 옵션에서 원하는 faker 데이터를 직접 선택할 수 있습니다.

목 값은 고정 값으로도 입력할 수 있습니다.

XML 설정

XML 데이터의 경우, Apidog의 Type Editor는 추가 XML Settings를 제공합니다. XML 스위치를 활성화하고 태그 이름, 네임스페이스 등의 속성을 구성한 다음, 해당 XML 구조를 미리 볼 수 있습니다.

HashMap, Dictionary, Array

HashMap은 Map, dictionary 또는 associative array라고도 합니다. 이는 키-값 쌍의 컬렉션이며, 키 이름은 사전에 정의된 것이 아니라 어떤 내용이든 될 수 있습니다.

OpenAPI 사양은 문자열 키가 있는 HashMap 정의를 지원합니다. 이는 요소 유형을 object로 설정한 다음, additionalProperties 키워드를 사용하여 키-값 쌍에서 값의 유형을 지정함으로써 수행됩니다.

사용자 정보 조회 API가 있고, 반환 데이터 형식에 다음 요구 사항이 있다고 가정하겠습니다.

반환 데이터는 객체입니다.

객체의 하위 요소는 HashMap의 키-값 쌍입니다.

사용자 ID가 키이고 사용자 정보가 값입니다.

Apidog에서 이를 정의하려면:

새 스키마를 생성하고 이름을 "UserProfiles"로 지정하십시오.

"UserProfiles"에서 루트 노드를 "object" 유형으로 지정하십시오. 그런 다음 Advanced Configuration을 클릭하고 additionalProperties를 Allow로 설정한 후 오른쪽의 Settings 버튼을 클릭하십시오.

팝업에서 필요한 사용자 정보를 추가하고, 사용자의 이름과 이메일을 객체의 필드로 설정하십시오. 자동으로 저장됩니다.

API 문서의 응답에서 루트 노드의 스키마를 참조하고 방금 생성한 "user profiles"를 선택하십시오.

저장을 클릭하면 API 문서 내 반환 응답 예시에서 정의된 스키마와 예시 값을 확인할 수 있습니다.

additionalProperties가 있는 객체

실제 개발 작업이 반복됨에 따라 API가 반환하는 객체는 원래 정의된 객체와 비교하여 additionalProperties를 가질 수 있습니다. OpenAPI 사양에 따르면, 이러한 상황도 "additionalProperties" 기능을 사용하여 처리할 수 있습니다.

현재 사용자 정보 조회 API가 있으며, 사용자 ID로 사용자 정보를 조회할 때 원래 정의된 응답 필드가 name 및 email이었다고 가정하겠습니다. 이제 시스템 업그레이드에 따라 다른 필드를 포함하고자 합니다.

API 문서를 편집할 때 다음과 같이 정의할 수 있습니다. 데이터 모델의 루트 노드에서 Advanced Settings를 클릭하고 additionalProperties를 Allow로 설정한 다음, 필드 값 유형을 any로 설정하십시오.

그러면 API 문서에서 정의된 데이터 구조와 예시 값을 확인할 수 있습니다.

튜플

일반적으로 배열의 내부 요소는 동일한 유형이어야 하지만, 튜플은 서로 다른 유형의 데이터를 포함할 수 있습니다. (0,"A",2,"C")와 같이 문자열 및 정수 유형을 모두 포함하는 튜플을 정의하려면, 데이터 모델에서 요소 유형을 array로 설정한 다음 조합 패턴에서 items의 유형을 anyOf로 설정하고, 각각 string 및 integer 유형의 하위 요소를 추가할 수 있습니다.

TIP

예시를 생성할 때 여러 요소를 생성하려면 루트 노드의 고급 설정에서 요소의 최소 및 최대 개수를 지정하십시오.

저장한 후 API 문서에서 Generate Automatically를 클릭하면 정의된 데이터 구조와 예시 값을 확인할 수 있습니다.

문서의 반환 응답에서도 튜플의 예시 값을 확인할 수 있습니다.

도구

Apidog의 Schema Editor는 매우 유용한 여러 도구를 제공합니다.

도구	설명
Generate from JSON etc.	이 도구를 사용하면 JSON, XML 데이터 및 기타 소스에서, 또는 데이터베이스 테이블 구조에서 직접 스키마를 자동 생성할 수 있습니다. Generate schemas from JSON etc.에 대해 자세히 알아보십시오.
Preview	이 도구는 스키마 정의를 준수하는 목 데이터를 생성하여 예상 데이터의 미리 보기를 제공합니다.
Generate code	이 도구는 다양한 프로그래밍 언어로 데이터 구조 정의 코드를 생성할 수 있습니다. Generate code에 대해 자세히 알아보십시오.
JSON Schema	이 도구를 사용하면 세부 조정 및 사용자 지정을 위해 JSON schema를 직접 편집할 수 있습니다.

FAQ

Q: 문자열 속성에 여러 열거형 값이 있고 다양한 위치에서 사용되는 경우, 이 enum을 전체에서 일관되게 참조하려면 어떻게 해야 합니까?

A: 이 속성을 단일 속성으로 구성된 독립 스키마로 정의하면, API 문서의 여러 부분에서 일관되게 참조할 수 있습니다.

스키마 구축

Schema Editor 활용#