Apidog를 사용하여 게시된 온라인 API 문서를 열면 각 엔드포인트 옆에 "Try it" 버튼이 있는 것을 볼 수 있습니다. 이 버튼을 클릭하면 페이지 오른쪽에 디버그 패널이 나타나 문서 내에서 직접 API를 테스트할 수 있습니다.
하지만 이 "디버그" 기능의 유용성은 플랫폼 내에서 얼마나 잘 구성했는지에 크게 좌우됩니다. 올바른 URL 설정, 인증 구성, 명확한 파라미터 구조, 완전한 예시 데이터와 같은 요소들이 디버깅 경험에 큰 영향을 미칩니다.
제대로 구성되지 않으면 사용자는 파라미터를 채우는 데 많은 시간을 소비하거나 심지어 API 호출에 실패할 수도 있어 이상적이지 않습니다.
게시된 온라인 문서가 훌륭한 디버깅 경험을 제공하도록 Apidog를 효과적으로 구성하는 방법을 논의해 보겠습니다.
올바른 URL 구성
종종 온라인 문서는 괜찮아 보이지만, "Try it" 버튼을 클릭하여 요청을 보낼 때 실패합니다. 가장 흔한 이유는 게시 중에 런타임 환경을 선택하지 않아 엔드포인트에 /pet/{petId}와 같은 경로만 포함되기 때문입니다.
이로 인해 프로토콜이나 호스트 이름이 없는 불완전한 요청 URL이 생성되어 요청 전송 시 오류가 발생합니다.
이를 해결하려면 사용자가 올바른 URL에 액세스할 수 있도록 해야 합니다. Apidog는 필요에 따라 온라인 문서의 URL을 구성하는 세 가지 방법을 제공합니다.
1. 기본 URL 사용
이것이 권장되는 접근 방식입니다. 엔드포인트에 /pet/{petId}와 같은 경로만 정의하고, "환경 관리" 섹션에서 전체 서비스 주소(예: https://product.example.com)를 기본 URL로 구성합니다.
API 문서를 게시할 때 적절한 런타임 환경을 선택합니다. Apidog는 기본 URL과 엔드포인트 경로를 자동으로 연결합니다. 각기 다른 기본 URL을 가진 여러 런타임 환경을 정의할 수도 있습니다.
온라인 문서에서 사용자는 드롭다운 목록에서 환경을 빠르게 전환할 수 있으며, 모든 엔드포인트 URL이 그에 따라 업데이트됩니다. 이를 통해 다양한 환경에서 API를 편리하게 검증할 수 있습니다.
참고: 프로토콜 문제에 유의하십시오. 많은 브라우저는 HTTPS 페이지가 HTTP API를 호출하는 것을 제한합니다. API가 HTTP를 사용하는 경우, 사용자는 HTTPS 문서 페이지에서 디버깅할 때 교차 프로토콜 문제를 겪을 수 있습니다.
2. 엔드포인트에 전체 URL 포함
또 다른 옵션은 https://product.example.com/pet/{petId}와 같이 엔드포인트에 전체 URL을 직접 지정하는 것입니다.
이렇게 하면 선택된 런타임 환경과 관계없이 완전한 요청 URL이 표시됩니다. 하지만 서버 주소 변경을 관리하는 것이 번거로워지는데, 각 엔드포인트를 개별적으로 업데이트해야 하기 때문입니다. 따라서 이 방법은 덜 권장됩니다.
3. URL에 변수 사용
사용자가 디버깅을 위해 URL을 사용자 정의하기를 원한다면 변수를 사용할 수 있습니다. 예를 들어, "환경 관리" 섹션에서 BaseURL 환경 변수를 생성하고 기본 URL에서 {{BaseURL}}로 참조합니다.
온라인 문서에서 사용자는 변수 이름을 클릭하고 원하는 URL로 수정할 수 있습니다.
또는 {{BaseURL}}/pet/{petId}와 같이 엔드포인트에 직접 변수를 정의할 수 있습니다.
온라인 문서의 해당 특정 엔드포인트에서 사용자는 요청을 보내기 위해 변수 값을 설정할 수 있습니다.
문서를 게시하기 전에 환경의 "초기 값"에 민감한 정보(예: 인증 자격 증명)가 포함되어 있지 않은지 확인하십시오. 이러한 값은 게시된 문서에 포함되어 개인 정보 보호 위험을 초래할 수 있습니다.
올바른 인증 구성
기본 인증 설정
성공적인 엔드포인트 요청에는 종종 인증이 필요합니다. Apidog는 Bearer Token, API Key, OAuth2.0, Basic Auth를 포함한 다양한 인증 유형을 지원합니다.
보안 스키마를 사용하거나 수동으로 설정하여 엔드포인트 또는 폴더 수준에서 인증을 구성할 수 있습니다.
예를 들어, Bearer Token을 인증 유형으로 사용할 때 온라인 문서의 디버그 패널 상단에 "토큰" 필드가 나타납니다. 사용자는 "Bearer" 접두사를 수동으로 추가할 필요 없이 토큰 값을 직접 입력할 수 있습니다. Apidog는 이를 자동으로 처리하여 수동으로 인증 헤더를 추가하는 것보다 훨씬 편리합니다.
이 설정의 장점은 인증 정보가 여러 엔드포인트에서 공유될 수 있다는 것입니다. 여러 엔드포인트가 동일한 보안 스키마 또는 유형을 사용하는 경우, 자격 증명을 한 번만 입력하면 됩니다. 자격 증명에 대한 모든 업데이트는 관련 모든 엔드포인트에 자동으로 적용됩니다.
인증 자격 증명은 암호화되어 사용자 브라우저에 로컬로 저장되며, 세션별로 관리되고 탭과 창 간에 공유됩니다. 브라우저가 닫히면 지워지므로 게시된 문서에서 민감한 정보가 노출될 위험을 줄여줍니다.
OAuth2.0 구성
OAuth2.0 인증의 경우, 사용자가 디버깅 중에 토큰을 직접 생성하기를 원한다면 프로젝트에서 인증 서버 세부 정보(예: 인증 URL, 토큰 URL)를 구성하십시오.
OAuth2.0 보안 스키마를 사용할 때 사용자는 디버깅 중에 클라이언트 ID, 클라이언트 시크릿 등을 입력해야 합니다. 팝업이 인증 프로세스를 안내하며, 획득한 access_token은 후속 API 요청에 자동으로 적용됩니다.
명확한 파라미터 구조 설계
디버그 패널의 파라미터 표시
디버그 패널은 엔드포인트 설계에 따라 파라미터 섹션을 지능적으로 표시합니다. 예를 들어, 엔드포인트가 경로 파라미터만 정의하는 경우 디버그 패널은 경로 섹션만 표시하여 불필요한 쿼리 또는 본문 섹션을 피합니다.
이러한 명확성은 사용자가 관련 없는 섹션에 방해받지 않고 어떤 파라미터를 채워야 하는지 이해하는 데 도움이 됩니다.
예시 제공
엔드포인트를 설계할 때 각 파라미터의 유형과 필수 속성을 정확하게 정의하십시오. 명확한 설명과 예시를 포함하면 디버그 패널에 미리 채워져 사용성을 향상시킬 수 있습니다.
중복 헤더 피하기
엔드포인트가 본문 파라미터를 정의하는 경우, Content-Type: application/json과 같은 헤더를 수동으로 추가할 필요가 없습니다. Apidog는 요청 중에 이러한 헤더를 자동으로 처리합니다.
마찬가지로, 인증이 구성된 경우 헤더에서 중복하지 마십시오. 인증 설정이 우선하며 충돌하는 모든 헤더 구성을 재정의합니다.
포괄적인 요청 예시 제공
복잡한 JSON 요청 본문을 가진 엔드포인트의 경우, 설계 시 여러 요청 본문 예시를 제공하십시오.
사용자는 디버그 패널의 드롭다운 메뉴에서 이러한 예시를 선택할 수 있어 시간을 절약하고 오류를 줄일 수 있습니다.
예시 데이터가 실제 시나리오와 밀접하게 유사한지 확인하되, 민감한 정보는 포함하지 마십시오. 사용자는 필요에 따라 이러한 예시를 수정할 수 있습니다.
명확한 응답 예시 구성
요청을 보낸 후 디버그 패널은 상태 코드, 헤더 및 본문을 포함한 전체 응답을 표시합니다. 문서 작성자로서 사용자가 가능한 결과를 이해하는 데 도움이 되도록 명확한 응답 예시를 구성하십시오.
성공(200), 잘못된 요청(400), 권한 없음(401)과 같이 각 엔드포인트에 대해 여러 응답 예시를 제공하십시오.
오류 응답에 특별히 주의를 기울여, 다양한 시나리오에 대한 오류 코드와 메시지 형식을 명확하게 설명하십시오. 이는 사용자가 디버깅 중에 문제를 신속하게 식별하고 해결하는 데 도움이 됩니다.
통합을 위한 예시 코드 제공
Apidog가 일반적인 프로그래밍 언어에 대한 예시 코드를 자동으로 생성하지만, 생성된 코드가 비즈니스 요구 사항과 완전히 일치하지 않을 수 있습니다. 이러한 경우 예시를 사용자 정의하십시오.
"프로젝트 설정 -> 엔드포인트 기능 설정 -> 요청 코드 샘플"에서 자동 생성 예시가 필요한 언어를 구성할 수 있습니다.
또한 "엔드포인트 설명" 섹션에서 특정 엔드포인트에 대한 사용자 정의 예시 코드를 작성할 수 있습니다.
이를 통해 사용자는 온라인 문서에서 자동 생성된 예시와 사용자 정의 예시를 모두 볼 수 있어 통합이 더 쉬워집니다.
요약
온라인 문서의 디버깅 경험은 올바른 구성에 크게 좌우됩니다. URL, 인증, 파라미터 구조 및 예시를 신중하게 설정함으로써 사용자가 기술적인 세부 사항에 얽매이지 않고 API를 빠르게 시작할 수 있도록 보장할 수 있습니다.