스키마 번들과 변환 경고
APIFuse 개발자 스키마 번들에 포함되는 아티팩트와 변환 경고의 의미, 변경 감지 방법을 설명합니다.
스키마 번들과 변환 경고
스키마 번들은 하나의 공개 provider operation에 대한 개발자 아티팩트 묶음입니다. apifuse_dev_get_schema_bundle로 가져오며, API 레퍼런스·OpenAPI 문서와 동일한 입출력 스키마를 사용합니다.
번들에 포함되는 것
- 입출력 JSON Schema
- OpenAPI operation 조각
- TypeScript 입출력 타입
- Zod 입출력 스키마
- Pydantic v2 입출력 모델
- 요청·응답 예시
- 인증 모드와 인가 요구사항
- 손실 변환 경고
- 버전과 해시:
artifactVersion,schemaHash,bundleHash,targetArtifactHash
변경 감지
bundleHash 또는 targetArtifactHash 값이 바뀌면 operation 계약이 변경된 것입니다. 생성된 타입을 다시 가져오고 애플리케이션 코드를 검토하세요. apifuse_dev_get_operation_spec과 apifuse_dev_get_schema_bundle은 같은 operation에 대해 동일한 schemaHash와 bundleHash를 반환합니다.
변환 경고
일부 JSON Schema 구조는 모든 대상 언어에서 정확히 표현할 수 없습니다. 이런 경우 APIFuse는 안전하지 않은 아티팩트 게시를 막거나, 명시적인 변환 경고와 함께 아티팩트를 제공합니다.
경고는 번들에 포함되며 번들 해시에 반영됩니다. 새로운 경고가 나타나면 계약 변경으로 간주하고, 배포 전에 생성된 유효성 검사 동작을 검토하세요.
경고 형식 예시:
{
"target": "pydantic",
"code": "lossy_union_discriminator",
"message": "The JSON Schema union could not be represented with an exact Pydantic discriminator.",
"path": ["output", "items"]
}