Blog

Apidog에 여러 요청 본문 예제 추가하는 방법

Young-jae

Young-jae

20 October 2025

Apidog에 여러 요청 본문 예제 추가하는 방법

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

Apidog은 각 엔드포인트에 대해 여러 요청 본문 예제를 추가하는 것을 지원합니다. 이로 인해 API 문서가 더욱 유용하고 OpenAPI 사양과 호환됩니다. 이 기능을 통해 동일한 엔드포인트에 대한 요청을 구조화하는 다양한 방법을 보여주어 개발자들이 다양한 상황에서 API를 사용하는 방법을 이해하는 데 도움을 줍니다.

요청 본문 예제는 아래와 같은 이유로 유용합니다:

모든 가능한 시나리오를 다루기 위해 필요한 만큼 추가할 수 있습니다.

단계별: 첫 번째 요청 본문 예제 추가하기

Apidog에서 요청 본문 예제를 추가하는 것은 간단합니다. 시작하는 방법은 다음과 같습니다:

1. Apidog에서 API 프로젝트를 엽니다 (버전 2.7.0 이상)

2. 예제를 추가할 엔드포인트로 이동합니다

3. "편집" 탭을 클릭하여 문서 편집기에 접근하고 "요청 본문" 섹션으로 스크롤합니다

4. "예제 추가"를 클릭하여 새 예제를 만듭니다

5. 예제 세부정보를 작성합니다:

요청 본문 예제 구성

6. "저장"을 클릭하여 예제를 생성합니다

예제 이름은 사용자가 각 예제의 목적을 식별하는 데 도움이 됩니다. 비워 두면 Apidog이 자동으로 "예제 1", "예제 2" 등으로 이름을 지정합니다.

예제 값은 유효한 요청 구조를 보여야 합니다. JSON 콘텐츠 유형의 경우 Apidog은 유효한 형식을 보장하기 위해 구조화된 편집기를 제공합니다.

설명 필드는 사용자가 이 특정 요청 구조를 언제, 왜 사용할지 설명하는 곳입니다. 여기에서 Markdown을 사용하면 설명이 더 명확해집니다.

OAS 키는 API 문서를 OpenAPI 형식으로 내보낼 계획이 있는 경우 중요합니다. 이 키는 내보낸 사양에서 예제를 식별하는 식별자가 됩니다.

다양한 시나리오에 대한 여러 예제 만들기

첫 번째 예제를 추가한 후에는 다양한 사용 사례에 대한 추가 예제를 만들고 싶을 것입니다:

  1. "+ 추가" 버튼을 다시 클릭하여 다른 예제를 만듭니다
  2. 시나리오를 명확하게 식별할 수 있는 독특한 이름을 부여합니다 (예: "최소 요청")
  3. 이 특정 시나리오에 대한 예제 값을 입력합니다
  4. 이 예제를 언제 사용하는지 설명하는 자세한 설명을 추가합니다
  5. 필요에 따라 OAS 키와 확장을 구성합니다
  6. "저장"을 클릭하여 예제를 추가합니다
  7. 모든 관련 시나리오에 대해 이 과정을 반복합니다
엔드포인트 문서에 다른 요청 본문 예제 추가

여러 예제를 만들 때는 다음과 같은 일반적인 시나리오를 고려하세요:

각 예제는 엔드포인트를 사용하는 다른 방법을 보여야 합니다. 이는 개발자들이 API를 작동시키는 전반적인 가능성을 이해하는 데 도움을 줍니다.

Apidog은 예제를 특정 순서로 표시합니다:

Apidog을 사용한 요청 본문 예제 문서화

가장 중요한 예제가 먼저 나타나도록 하려면, 그들에게 명확한 이름과 OAS 키를 부여하세요.

테스트를 위한 요청 본문 예제 사용하기

여러 요청 본문 예제의 가장 좋은 기능 중 하나는 테스트를 간소화하는 것입니다:

  1. 엔드포인트의 "실행" 페이지로 이동합니다
  2. 요청 구성에서 "자동 생성" 섹션을 찾습니다
  3. 드롭다운 메뉴를 클릭하여 사용 가능한 모든 예제를 봅니다
  4. 테스트할 예제를 선택합니다
  5. 선택한 예제로 요청 본문이 자동으로 채워집니다
  6. "전송"을 클릭하여 이 예제로 엔드포인트를 테스트합니다
테스트를 위한 요청 본문 예제 사용

이로 인해 다양한 요청 구조를 수동으로 입력하거나 붙여넣을 필요 없이 다양한 시나리오를 쉽게 테스트할 수 있습니다. 예제 간에 신속하게 전환하여 API가 다양한 입력을 처리하는 방법을 확인할 수 있습니다.

Apidog은 테스트 세션에서 예제를 생성할 수도 있습니다:

  1. "실행" 페이지에서 요청 본문을 구성합니다
  2. "추출" 버튼을 클릭합니다
  3. "요청 예제로 추출"을 선택합니다
  4. 새 예제를 만들거나 기존 예제를 업데이트할지 선택합니다
  5. 현재 요청 본문이 예제로 저장됩니다
예제로 요청 본문 추출

이것은 테스트 중에 작동하는 요청 구조를 찾아 이를 향후 참조나 문서화에 저장하고 싶을 때 유용합니다.

예제의 OpenAPI 호환성 보장하기

Apidog의 요청 본문 예제는 OpenAPI 사양과 원활하게 작동하도록 설계되었습니다. API 문서를 내보낼 때 모든 예제가 OAS 3.0/3.1 표준에 따라 적절하게 형식이 지정됩니다.

내보내는 동안 예제를 처리하는 방법은 다음과 같습니다:

  1. 각 예제가 내보낸 사양에 포함됩니다
  2. 예제 이름은 제공된 경우 OAS 키에서 가져옵니다 (제공되지 않은 경우 일련 번호에서 가져옴)
  3. 예제 설명은 내보낸 형식에 보존됩니다
  4. 사용자 정의 OAS 확장은 내보내기에 포함됩니다

내보내진 OpenAPI 사양에는 다음과 같은 구조로 예제가 포함됩니다:

"examples": {
  "standard_request": {
    "value": {
      "name": "John Doe",
      "id": "12345",
      "email": "john.doe@example.com"
    },
    "summary": "표준 요청",
    "description": "모든 필수 필드를 포함한 표준 요청입니다."
  },
  "minimal_request": {
    "value": {
      "id": "12345"
    },
    "summary": "최소 요청",
    "description": "필수 ID 필드만 포함된 최소 요청입니다."
  }
}

OpenAPI와의 호환성을 최상으로 보장하려면:

이렇게 하면 Apidog 내에서뿐만 아니라 OpenAPI 사양을 통해 공유할 때에도 예제가 가치 있게 유지됩니다.

요청 본문 예제에 대한 모범 사례

여러 요청 본문 예제에서 최상의 가치를 얻으려면 다음 모범 사례를 따르십시오:

포괄적인 예제 세트 만들기

다음과 같은 예제를 포함하십시오:

명확한 명명 사용하기

유용한 설명 작성하기

예제를 논리적으로 정리하기

OAS 키를 효과적으로 사용하기

이러한 모범 사례를 따르면, 개발자들이 API를 이해하고 효과적으로 사용할 수 있도록 돕는 요청 본문 예제를 만들 수 있습니다.

결론

Apidog에서 여러 요청 본문 예제를 추가하는 것은 API 문서를 개선하는 간단하면서도 강력한 방법입니다. 동일한 엔드포인트에 대한 요청을 구조화하는 다양한 방법을 보여줌으로써 개발자들이 API를 다양한 상황에서 사용하는 방법을 이해하는 데 도움을 줍니다.

단계별 과정은 직관적입니다:

  1. 엔드포인트로 이동하여 "편집"을 클릭합니다
  2. 요청 본문 섹션으로 스크롤하고 "+ 추가"를 클릭합니다
  3. 이름, 값, 설명 및 OAS 키로 예제를 구성합니다
  4. 추가 시나리오에 대해 반복합니다
  5. 테스트 및 문서화에 예제를 사용합니다

적절한 예제가 준비되면 API가 이해하기 쉽고, 테스트하고 구현하기 쉬워집니다. 이는 더 빠른 채택, 더 적은 지원 질문, 그리고 전반적으로 더 나은 개발자 경험으로 이어집니다.

오늘부터 Apidog 문서에 여러 요청 본문 예제를 추가하여 여러분과 API 사용자 모두에게 이점을 누려보세요.

버튼

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드