인트로스펙션 JSON

GraphQL SDL

인트로스펙션 JSON to SDL 변환기란?

Apollo Studio, Postman, Insomnia에서 스키마를 가져오거나, 운영 중인 엔드포인트에 get-graphql-schema를 실행하면 돌아오는 것은 여러분이 작성한 친근한 SDL이 아닙니다 — query { __schema { ... } }의 결과, 즉 600줄이 넘는 중첩된 JSON으로, 모든 타입, 모든 필드, 모든 수식자가 kind / name / ofType 객체 트리에 담겨 있습니다. 도구에는 유용하지만 사람이 읽기에는 무리입니다. 이 변환기는 그 JSON을 받아서, 여러분이 실제로 리포지토리에 커밋할 SDL로 다시 출력해 줍니다. 2021년 10월 GraphQL 스펙의 인트로스펙션 규칙을 따릅니다.

모든 작업은 브라우저 안에서 일어납니다 — 업로드 없음, AI 없음, 스키마가 어디로도 전송되지 않습니다. 변환 로직은 graphql-js가 내부에서 buildClientSchema와 printSchema로 하는 것을 그대로 재현합니다. __schema 트리를 순회하고, 인트로스펙션 전용 타입(__Schema, __Type, __Field 등)과 내장 스칼라를 건너뛰고, 남은 각 정의를 설명, 필드, 인자, 기본값, deprecation 사유까지 그대로 출력합니다. 전체 { "data": { "__schema": ... } } 봉투를 붙여넣든, { "__schema": ... }만 붙이든, 심지어 __schema 값만 단독으로 붙이든, 페이지가 세 가지 모두를 처리합니다.

출력은 스칼라가 먼저, 그다음 enum, 인터페이스, 유니온, 입력 타입, 마지막에 객체 타입 순으로 그룹화됩니다 — 각 그룹 안에서는 알파벳 순, 들여쓰기는 두 칸, 정의 사이에는 빈 줄 한 줄. 리포지토리의 <code>.graphql</code> 파일에 그대로 떨어뜨려도 될 만큼 멱등합니다.

변환기 사용법

세 단계입니다. 아래 버튼은 이 페이지에 실제로 있는 버튼입니다.

붙여넣기, 업로드, 또는 샘플 불러오기

왼쪽 입력 패널에 인트로스펙션 JSON을 붙여넣으세요 — 입력을 멈춘 뒤 1초도 안 되어 자동으로 변환되므로, Convert 버튼을 찾아 헤맬 필요가 없습니다. Apollo Studio나 Postman에서 내보낸 .json 파일이라면 업로드를, 현실적인 Order/Customer/Money 인트로스펙션 결과를 불러오려면 샘플을 누르세요. 일반적인 붙여넣기는 이렇게 시작합니다:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

내부의 { "__schema": ... } 값이나 단독 __schema 객체를 붙여넣어도 됩니다 — 페이지가 세 가지 형태를 모두 시도합니다. get-graphql-schema나 Apollo Server의 인트로스펙션 엔드포인트는 기본적으로 이 형태들 중 하나를 만들어냅니다.

SDL 출력 읽기

오른쪽 출력 패널이 스키마를 SDL로 렌더링합니다. 각 타입은 두 칸 들여쓰기로 자기 자신의 정의를 가지고, 필드는 한 줄에 하나씩, 설명은 타입이나 필드 위에 트리플 따옴표 블록 문자열로 유지되며, deprecation 사유는 @deprecated(reason: "...")로 같은 줄에 표시됩니다. 내장 스칼라와 __ 인트로스펙션 타입은 걸러집니다 — 결과적으로 여러분이 받는 것은 서버가 게시하는 스키마 그 자체이며, Relay의 GraphQL 스펙이 권장하는 문서화 방식과 일치합니다. JSON이 잘못되었거나 __schema 필드가 없으면 스택 트레이스 대신 친절한 인라인 메시지를 보여줍니다.

복사 또는 다운로드

PR 설명, 문서, 채팅에 SDL을 붙여 넣으려면 복사를 누르세요. schema.graphql로 저장하려면 다운로드를 — 그대로 리포지토리에 떨어뜨리세요. 입력 패널의 지우기 버튼은 빈 상태로 되돌립니다. 변환은 완전히 클라이언트 측에서 이루어지며, 인트로스펙션 결과가 페이지를 떠나는 일은 없습니다.

실제로 쓸 만한 상황

운영 중인 엔드포인트에서 스키마 캡처

리포지토리에 스키마 파일이 없고 운영 중인 서버만 있는 GraphQL 서비스를 인계받았을 때. 인트로스펙션 쿼리를 실행하고, JSON을 여기에 붙여넣으면 5분 안에 초기 schema.graphql이 커밋됩니다. 한 번 쓰자고 graphql-js의 buildClientSchema와 printSchema를 이어붙이는 것보다 훨씬 간편합니다.

Apollo Studio 또는 Postman 내보내기 읽기

Apollo Studio의 스키마 내보내기 결과는 인트로스펙션 JSON입니다. Postman의 GraphQL 요청에서 "Save schema" 버튼도 마찬가지. 여기서 변환하면 JSON을 노려보는 대신 코드 에디터에서 스키마를 슥슥 훑어볼 수 있습니다.

운영 스키마의 두 스냅샷 비교

staging과 production에 각각 인트로스펙션을 실행하고 SDL로 변환한 다음, 두 파일을 diff해 보세요. 누락된 필드나 이름이 바뀐 enum 값을 찾는 일은 SDL에서는 식은 죽이지만, 생 인트로스펙션 JSON에서는 사실상 불가능합니다.

내 것이 아닌 서비스의 타입 스텁 생성

서드파티 GraphQL API에 대한 TypeScript 타입이나 React 훅이 필요한가요? 대부분의 코드 제너레이터는 인트로스펙션 JSON이 아니라 SDL을 원합니다. 여기서 변환한 다음 SDL을 codegen 파이프라인에 넣으세요 — graphql-react, graphql-codegen, 또는 여러분의 스택이 쓰는 무엇이든.

자주 묻는 질문

꼭 { "data": { "__schema": ... } } 봉투 전체가 필요한가요?

아니요. 페이지는 세 가지 형태를 받습니다: GraphQL 응답 봉투 전체, { "__schema": ... }만, 혹은 단독 __schema 객체. 어느 것을 붙여 넣어도 __schema 루트를 찾아서 거기서부터 처리합니다.

JSON에 __schema 필드가 없으면요?

친절한 메시지가 나옵니다: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." 크래시도, 스택 트레이스도 없습니다.

설명과 deprecation 사유는 보존되나요?

네. 타입과 필드 설명은 정의 위에 트리플 따옴표 블록 문자열로 출력됩니다. 폐기된 필드와 enum 값은 같은 줄에 @deprecated(reason: "...")가 붙습니다. graphql-js의 printSchema 출력과 일치합니다.

내장 스칼라와 __ 인트로스펙션 타입은 어떻게 되나요?

걸러집니다. String, Int, Float, Boolean, ID는 SDL에서 암묵적입니다 — 필드 타입으로만 등장하고 최상위 정의로는 나오지 않습니다. __Schema, __Type, __Field를 비롯한 나머지 인트로스펙션 메타 타입도 마찬가지입니다.

출력이 원래의 인트로스펙션 결과로 정확히 왕복(round-trip)되나요?

의미상으로는 네 — SDL은 같은 스키마를 기술합니다. 바이트 단위로는 아니요, 타입과 필드의 순서가 원본 소스 파일과 다를 수 있기 때문입니다. 출력은 안정적인 diff를 위해 각 정의 그룹 내에서 알파벳 순으로 정렬됩니다.

제 인트로스펙션 결과가 서버로 전송되나요?

아니요. 변환은 전부 브라우저 안에서 실행됩니다. 어떤 것도 업로드되지 않고, 어떤 것도 기록되지 않습니다. 사내용이나 미공개 서비스의 스키마도 안심하고 붙여 넣으세요.

다른 GraphQL 도구

SDL이 손에 들어오면 나머지는 이쪽이 처리합니다:

인트로스펙션 JSON에서 GraphQL SDL로