JSON 응답 스키마 OpenAPI 생성기

JSON 샘플에서 응답 스키마를 추론하고 OpenAPI 3.0.3 YAML 경로 하나를 생성합니다.

응답 샘플과 엔드포인트

JSON 응답 샘플

고정 엔드포인트 경로

HTTP 메서드

생성된 OpenAPI YAML

openapi: 3.0.3
info:
  title: Generated API
  version: 1.0.0
paths:
  "/api/users":
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  schemas:
    Response:
      type: object
      required:
        - "id"
        - "name"
      properties:
        "id":
          type: integer
        "name":
          type: string

작동 방식

JSON 응답 샘플을 붙여 넣고 고정 경로를 입력한 뒤 GET, POST, PUT, DELETE 중 하나를 선택하세요. 생성기는 응답 본문 스키마를 추론해 OpenAPI 3.0.3 YAML 문서에 넣습니다.

응답에 포함될 수 있는 변화를 보여 주는 대표 샘플을 사용하세요. 같은 배열 위치에 여러 객체가 있으면 생성기가 속성을 결합하고 관찰된 모든 객체에 나타난 경우에만 필수로 표시합니다.

YAML을 사용하기 전에 추론된 타입과 필수 필드를 확인하세요. 요청 본문, 매개변수, 인증, 오류 응답, 경로 매개변수 선언은 직접 추가해야 합니다. 그런 다음 완성된 문서를 OpenAPI 검증기로 확인하세요.

JSON 예시는 있지만 응답 스키마가 없을 때 사용하세요. 제공한 샘플에서 선택한 경로와 메서드만 문서화합니다.

단계별 안내

JSON 응답 샘플 붙여 넣기
고정 경로를 설정하고 메서드 선택
응답 스키마 확인 및 복사

작성 예시

GET /api/users의 경우 {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}를 붙여 넣으세요. 이 샘플에는 중첩 객체, 여러 값이 섞인 배열, 두 개의 측정 객체가 있습니다.

출력에서는 user, tags, metrics가 필수로 표시됩니다. 두 측정 객체 모두 count를 포함하므로 이 위치에서도 필수입니다. score와 active는 각각 하나의 객체에만 있어 선택 항목입니다. tags는 문자열이나 정수를 허용합니다. 샘플에 null도 있으므로 관찰된 두 타입 모두 nullable입니다.

이 도구를 사용할 때

경로를 문서화할 때 JSON 응답 본문 예시를 초기 OpenAPI 응답 스키마로 바꾸는 데 사용하세요.

관찰된 응답 형태를 정리하는 데 유용합니다. 생성된 문서에는 API의 요청, 보안, 오류, 매개변수 세부 정보가 더 필요합니다.

흔한 실수

객체가 하나뿐이면 포함된 모든 속성이 필수처럼 보입니다. 응답에 따라 달라지는 속성을 찾으려면 같은 배열 위치에 대표 객체를 여러 개 제공하세요.

추론된 출력을 완전한 API 정의로 여기지 마세요. null 처리, 선택 필드, 배열 변형, 고정 경로를 확인한 뒤 도구 범위 밖인 요청 및 오류 세부 정보를 추가하세요.

추론 규칙

각 객체 위치에서 필수 키 = 관찰된 모든 객체에 있는 키입니다.

각 값에서 추론된 스키마 = 관찰된 null 이외 타입의 합집합입니다.

알려진 타입과 null이 함께 관찰되면 해당 타입 스키마를 nullable로 표시합니다.

이 추론은 샘플을 기반으로 하며 실행 중인 계약을 검사하지 않습니다. 하나의 예시로는 운영 응답에서 생략될 수 있는 필드를 알 수 없습니다.

한계와 가정

결과는 샘플에서 관찰된 값을 설명합니다. 모든 예시에서 빠진 필드를 찾거나 운영 환경에서 선택 항목임을 증명하거나 빈 배열의 항목 타입을 추론할 수 없습니다. null만 있는 값은 타입을 추론할 수 없습니다. 여러 값은 대안으로 표시되므로 API 계약과 비교해야 할 수 있습니다.

주요 용어

OpenAPI 문서: OpenAPI 문서는 API의 경로, 작업, 입력, 응답 및 기타 세부 정보를 기계가 읽을 수 있는 형식으로 설명합니다.
스키마: 스키마는 이름이 지정된 속성을 가진 객체처럼 데이터의 예상 구조와 값 타입을 설명합니다.
필수 속성: 이 출력에서 필수란 해당 위치의 관찰된 모든 객체에 속성이 있었다는 뜻입니다. 운영 동작을 증명하지는 않습니다.

FAQ

샘플은 어떻게 응답 스키마가 되나요?

생성기는 JSON 샘플의 모든 값을 살펴봅니다. 객체 속성을 만들고 모든 배열 항목을 확인하며 필요하면 anyOf로 관찰된 타입을 결합합니다. 예시의 tags 배열에는 문자열, null, 정수가 있으므로 항목 스키마는 nullable 문자열 또는 nullable 정수를 허용합니다.

null과 다른 타입은 어떻게 표현되나요?

객체는 속성을 가진 스키마가 됩니다. 같은 위치의 관찰된 모든 객체에 있는 속성은 필수로 표시됩니다. 관찰된 타입이 서로 다르면 anyOf를 사용합니다. null과 다른 타입이 관찰되면 해당 타입 스키마에 nullable: true를 설정합니다. null만 있는 값은 타입을 추론할 수 없으므로 스키마에 제약을 두지 않습니다.

생성된 문서에는 무엇이 포함되나요?

문서에는 하나의 경로, 선택한 GET, POST, PUT, DELETE 메서드, 성공한 200 JSON 응답이 포함됩니다. 스키마는 components에 저장되고 응답에서 참조됩니다. 생성기는 요청 본문, 매개변수, 보안 규칙, 오류 응답, 헤더를 만들지 않습니다.

ID 같은 경로 매개변수를 입력할 수 있나요?

경로는 /api/users처럼 슬래시로 시작하는 고정 경로여야 합니다. /api/users/{id} 같은 템플릿에는 선언된 경로 매개변수도 필요하지만 이 생성기는 이를 추가하지 않으므로 중괄호가 있는 경로는 거부됩니다.

완전한 API 계약을 만들거나 검증하나요?

아니요. 출력은 예시 응답 본문을 설명합니다. 요청 스키마를 추론하거나 생성된 YAML을 OpenAPI 사양과 대조해 검증하지 않습니다. 다른 작업과 응답 세부 정보를 추가한 뒤 완성된 문서를 OpenAPI 검증기로 확인하세요.

출처

OpenAPI Initiative: OpenAPI Specification 3.0.3