Apidog 필드 열거형 설정 방법 (문자열, 배열 등)

안녕하세요! Apidog를 사용하여 API 디자인에 뛰어들고 인터페이스를 명확하게 만들고 싶다면, 열거형(또는 enum) 설정은 필수입니다. 열거형을 사용하면 사용자 상태에 대한 "active", "frozen", "deleted"와 같이 필드에 대한 고정된 값 집합을 정의하여 개발자가 해당 옵션 중에서만 선택하도록 보장할 수 있습니다. 이는 성가신 오류를 방지하고 API 문서를 명확하게 유지합니다. 이 대화형 가이드에서는 Apidog의 직관적인 UI와 AI 기반 기능을 사용하여 문자열, 배열 등에 대한 열거형을 설정하는 방법을 살펴보겠습니다. 초보자든 숙련된 개발자든 관계없이 곧 전문가처럼 Apidog 열거형을 설정하게 될 것입니다. 시작해 봅시다!

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

최대 생산성으로 개발팀이 함께 작업할 수 있는 통합 올인원 플랫폼을 원하십니까?

Apidog는 귀하의 모든 요구 사항을 충족하며, 훨씬 더 저렴한 가격으로 Postman을 대체합니다!

버튼

Apidog에서 열거형을 사용하는 이유

열거형은 API 필드를 위한 가드레일과 같습니다. "active", "frozen", "deleted"만 유효한 "사용자 상태" 필드를 상상해 보세요. 열거형이 없으면 개발자가 실수로 "inactive" 또는 "banned"를 전달하여 API에 문제를 일으킬 수 있습니다. Apidog 열거형을 설정하면 허용된 값을 명시적으로 나열하여 문서를 명확하게 하고 오류를 줄일 수 있습니다. 또한 Apidog의 Mock 데이터 기능은 이러한 열거형을 자동으로 준수하여 규칙을 따르는 테스트 데이터를 생성합니다. "pending"과 같은 문자열이든 특정 권한의 배열이든, 열거형은 협업을 간소화하고 API를 견고하게 유지합니다.

API 설계, 디버깅 및 테스트를 위한 강력한 플랫폼인 Apidog는 문자열, 정수, 숫자 및 배열을 포함한 다양한 데이터 유형에 대한 열거형을 지원합니다. 각 값에 설명을 추가하여 명확성을 높일 수도 있습니다. 기본 문자열부터 복잡한 배열까지 설정 방법을 살펴보고, AI 및 재사용 가능한 모델이 어떻게 작업을 더 쉽게 만들 수 있는지 알아보겠습니다.

Apidog에서 기본 열거형 설정하기

가장 간단한 경우부터 시작하겠습니다: 사용자 상태 또는 주문 상태와 같이 문자열 또는 숫자 필드에 대한 열거형을 설정하는 것입니다. 방법은 다음과 같습니다.

인터페이스 편집기 열기:

Apidog에서 프로젝트로 이동하여 작업 중인 인터페이스(엔드포인트)를 엽니다. 요청 또는 응답 본문에서 user_status와 같이 제한하려는 필드를 찾습니다.

2. 데이터 유형 선택:

필드 설정에서 드롭다운에서 데이터 유형을 선택합니다. 일반적으로 string("active"의 경우), integer 또는 number입니다. 예를 들어, user_status에 대해 string을 선택합니다.

3. 고급 설정 액세스:

필드 유형 옆에 있는 고급 설정 버튼을 클릭합니다. 열거형을 구성할 수 있는 패널이 열립니다.

4. 열거형 값 추가:

열거형 값 섹션에서 허용된 값을 한 줄에 하나씩 입력합니다. user_status의 경우 다음을 추가할 수 있습니다.
active (설명: "사용자가 활성 상태이며 로그인할 수 있습니다")
frozen (설명: "사용자 계정이 일시적으로 정지되었습니다")
deleted (설명: "사용자 계정이 영구적으로 삭제되었습니다")
선택적으로 각 값에 설명을 추가하여 문서를 더 명확하게 만들 수 있습니다.

5. 저장 및 문서 확인:

변경 사항을 저장합니다. API 문서에서 Apidog는 이 값들을 해당 필드의 유일한 유효한 옵션으로 표시합니다. 팀원들은 "user_status: [active, frozen, deleted] 중 하나여야 합니다."와 같은 내용을 보게 될 것입니다.

Apidog에서 디버깅할 때, 드롭다운에서 이 열거형 값들을 직접 선택하여 테스트 요청이 유효한지 확인할 수 있습니다. 이는 모든 사람이 같은 내용을 이해하도록 하는 간단한 방법입니다!

전문가 팁: 열거형 패널의 대량 편집 기능을 사용하여 여러 값을 한 번에 붙여넣어 긴 목록에 대한 시간을 절약하세요.

Apidog에서 배열 열거형 처리하기

배열 열거형은 약간 더 까다롭지만 사용자 권한 또는 좌표와 같은 필드에 매우 유용합니다. Apidog는 개별 배열 요소를 제한하거나 전체 배열을 특정 조합으로 제한하는 두 가지 유형의 배열 열거형을 지원합니다. 자세히 살펴보겠습니다.

시나리오 1: 배열 요소 값 제한하기

"read", "write", "delete" 중 하나여야 하는 문자열 배열인 permissions 필드가 있다고 가정해 봅시다. 유효한 배열은 ["read"], ["write", "delete"] 또는 ["read", "write", "delete"]일 수 있습니다. 설정 방법은 다음과 같습니다.

필드를 배열 유형으로 설정:

인터페이스 편집기에서 필드(예: permissions)를 array 유형으로 설정합니다.

2. 하위 요소 유형 구성:

배열 설정에서 하위 요소 유형 옵션을 볼 수 있습니다. string(또는 integer와 같은 다른 유형)을 선택합니다.

3. 열거형 값 추가:

하위 요소에 대한 고급 설정을 클릭합니다. 열거형 값 섹션에 다음을 추가합니다.
read (설명: "읽기 전용 액세스")
write (설명: "쓰기 액세스")
delete (설명: "삭제 액세스")

4. 선택 사항: 고유성 강제 적용:

배열의 고급 설정에서 모든 요소는 고유해야 함을 활성화하여 중복을 방지합니다(예: ["read", "read"]는 유효하지 않게 됨).

5. 저장 및 테스트:

저장하면 문서에 배열의 요소가 이 값들로 제한됨이 표시됩니다. Mock 데이터는 열거형 및 고유성 규칙을 준수하여 ["read", "write"]와 같은 배열을 생성합니다.

또는 고급 설정 탭에서 JSON 스키마를 수동으로 편집할 수 있습니다.

{
  "type": "array",
  "items": {
    "type": "string",
    "enum": ["read", "write", "delete"]
  },
  "uniqueItems": true
}

이는 배열의 모든 요소가 열거형을 준수하도록 보장합니다.

시나리오 2: 전체 배열 값 제한하기

때로는 coordinate 필드가 [0, 0] 또는 [100, 100]만 될 수 있는 것처럼, 전체 배열이 몇 가지 고정된 조합 중 하나이기를 원할 수 있습니다. 방법은 다음과 같습니다.

필드를 배열 유형으로 설정:

필드(예: coordinate)에 대해 array를 선택합니다.

2. JSON 스키마 편집:

고급 설정에서 JSON 스키마 편집기로 전환하여 다음을 입력합니다.

{
  "type": "array",
  "enum": [
    [0, 0],
    [100, 100]
  ]
}

이는 필드를 정확히 이 배열들로 제한하며, [0, 100]과 같은 다른 조합은 허용되지 않습니다.

3. 저장 및 확인:

저장하면 문서에 [0, 0]과 [100, 100]이 유일한 유효한 값으로 나열됩니다. Mock 데이터는 이 배열 중 하나를 무작위로 선택합니다.

이 접근 방식은 덜 일반적이지만 사전 정의된 설정 또는 고정된 데이터 구조와 같은 특정 사용 사례에 강력합니다.

AI를 사용하여 열거형 설정 간소화하기

복잡한 열거형, 특히 배열에 대한 JSON 스키마를 작성하는 것은 구문과 씨름하는 것처럼 느껴질 수 있습니다. 다행히도 Apidog의 AI 기능이 여러분을 도와줄 것입니다! 열거형 요구 사항을 일반 언어로 설명하면 올바른 구성을 생성해 줍니다.

Apidog에서 AI 활성화:

팀 설정 > AI 기능으로 이동하여 AI 지원을 활성화합니다. 자세한 내용은 Apidog의 도움말 문서를 확인하세요.

2. 요구 사항 설명:

인터페이스 편집기에서 AI 채팅 패널을 열고 다음과 같이 입력합니다.

coordinate[1, 2][3, 4]

또는 문자열의 경우: "status를 pending, paid 또는 completed로 제한합니다."

3. 미리 보기 및 적용:

AI가 다음과 같이 JSON 스키마를 생성합니다.

{
  "type": "array",
  "enum": [
    [1, 2],
    [3, 4]
  ]
}

출력을 검토한 다음 적용을 클릭하여 필드에 추가합니다.

4. 테스트:

열거형이 올바른지 확인하기 위해 문서를 확인합니다. Apidog 인터페이스에서 열거형 값을 사용하여 디버깅을 시도해 보세요.

AI는 복잡한 스키마 또는 JSON 구문에 대해 확신이 없을 때 매우 유용합니다. 구글링보다 빠르고 정확성을 보장합니다.

Mock 데이터 및 열거형

Apidog의 가장 멋진 기능 중 하나는 열거형을 Mock 데이터와 통합하는 방식입니다. 열거형을 설정하면 Apidog의 Mock 서비스가 제한 사항을 준수하는 테스트 데이터를 자동으로 생성합니다. 예를 들어:

문자열 열거형: status가 ["active", "frozen", "deleted"]로 제한되면, Mock 데이터는 이 값들 중 하나를 무작위로 선택합니다.
고유 요소가 있는 배열 열거형: ["read", "write", "delete"] 권한 배열에 고유성이 활성화된 경우, ["read", "write"]를 얻을 수 있지만 ["read", "read"]는 절대 얻을 수 없습니다.
고정 배열 열거형: [[0, 0], [100, 100]]를 가진 coordinate 필드는 이 정확한 배열 중 하나만 반환합니다.

이는 테스트 데이터가 API 사양과 일치하도록 보장하여 디버깅 및 협업을 원활하게 만듭니다. Mock 데이터를 활성화하려면 인터페이스 편집기에서 Mock 옵션을 토글하고 결과를 미리 봅니다.

재사용 가능한 열거형 모델 정의하기

사용자 생성, 업데이트 및 목록 API의 user_status와 같이 여러 엔드포인트에 동일한 열거형이 나타나는 경우, 매번 재정의하는 것은 번거롭습니다. Apidog를 사용하면 재사용 가능한 데이터 모델을 생성하여 일관성을 유지할 수 있습니다.

데이터 모델 생성:

Apidog 프로젝트에서 데이터 모델로 이동합니다.
새 모델을 클릭하고 이름을 지정한 다음(예: UserStatusEnum), 루트 노드를 string으로 설정합니다.
고급 설정에서 active, frozen, deleted와 같은 열거형 값을 선택적 설명과 함께 추가합니다.

2. 모델 참조:

모든 인터페이스에서 필드의 유형을 참조로 설정하고 UserStatusEnum을 선택합니다.

3. 한 번 업데이트, 모든 곳에 동기화:

새 상태(예: suspended)를 추가해야 하는 경우 UserStatusEnum 모델을 업데이트하면 모든 참조 엔드포인트가 자동으로 업데이트됩니다.

이 접근 방식은 시간을 절약하고 프로젝트 전반에 걸쳐 일관성을 보장합니다. 여러 개발자가 동일한 열거형에 의존하는 팀에 적합합니다.

일반적인 열거형 문제 해결

문서에 열거형이 표시되지 않습니까? 인터페이스를 저장하고 문서 페이지를 새로 고칩니다. 필요한 경우 필드가 필수로 표시되어 있는지 확인합니다.
Mock 데이터가 열거형을 무시합니까? 고급 설정 또는 JSON 스키마에서 열거형 값이 올바르게 설정되었는지 확인합니다. Mock 옵션을 껐다가 켜봅니다.
배열 열거형 오류? 요소 수준 열거형의 경우 하위 요소 유형이 올바르게 설정되었는지 확인합니다. 고정 배열의 경우 JSON 스키마 구문을 확인합니다.
AI가 스키마를 생성하지 않습니까? 프롬프트를 명확히 하고(예: "정확한 배열로 제한") 팀 설정에서 AI가 활성화되어 있는지 확인합니다.

열거형이 Apidog를 빛나게 하는 이유

Apidog 열거형은 API 설계의 판도를 바꿉니다. 이는 필드 제한을 명확히 하고 오류를 줄이며 문서 가독성을 높입니다. AI 기능은 복잡한 설정을 간소화하고, 재사용 가능한 모델은 일관성을 보장합니다. Mock 데이터 통합은 테스트가 항상 사양을 준수함을 의미합니다. Postman과 같은 도구와 비교할 때, Apidog의 시각적 편집기와 AI는 열거형 설정, 특히 배열에 대한 설정을 더 직관적으로 만듭니다. 사용자들은 Apidog가 "API 문서를 완벽하게 만든다"고 칭찬하며, 열거형 지원을 통해 그 이유를 쉽게 알 수 있습니다.

결론

문자열, 숫자 또는 배열을 제한하든 Apidog 열거형을 설정하는 것은 식은 죽 먹기입니다. 시각적 편집기부터 AI 기반 JSON 스키마 생성에 이르기까지 Apidog는 API를 견고하고 개발자 친화적으로 만듭니다. 재사용 가능한 열거형 모델을 만들거나 AI를 사용하여 작업을 빠르게 처리해 보고, 댓글로 팁을 공유해 주세요. 함께 API 설계를 더 원활하게 만들어 봅시다!

💡

버튼