기본적으로 문서는 [subdomain].apidog.io 도메인에서 접근할 수 있습니다. 그러나 사용자 지정 도메인을 설정하여 이를 변경할 수 있으며, 이를 통해 사용자는 조직에 적합한 도메인에서 문서에 접근할 수 있습니다.사용자 지정 도메인은 관리자 권한이 있는 사용자가 설정할 수 있습니다. 사용자 지정 도메인을 설정하려면 다음 단계를 따르십시오.사용자 지정 도메인 설정 시작하기#
프로젝트의 Share 모듈에서 프로젝트의 사용자 지정 도메인 설정 옵션에 접근할 수 있습니다. 사이드바에서 Share Docs 메뉴를 클릭한 다음, 보조 메뉴에서 Publish 설정 페이지로 이동하십시오.Custom Domain이라는 섹션이 표시됩니다. 사용자 지정 도메인 설정을 시작하려면 Edit 버튼을 클릭하십시오.사용자 지정 도메인을 설정하는 옵션에는 두 가지 유형이 있습니다.1.
CNAME: 권장 옵션입니다. 설정 및 유지 관리가 가장 쉽습니다. 또한 하위 도메인 또는 루트 도메인에 대해 사용자 지정 도메인을 설정할 수 있으므로 가장 유연한 옵션입니다.
2.
Reverse Proxy: 이 옵션 은 더 고급 옵션이며 Content Delivery Network(CDN)를 사용하거나 자체 서버에 리버스 프록시를 설정해야 합니다. 이러한 기술에 익숙한 사용자에게 권장됩니다.
CNAME 구성하기#
이전 단계에서 CNAME 옵션을 선택한 경우에만 적용됩니다.
CNAME 레코드 구성하기#
레코드를 구성하기 위해 실제로 입력해야 하는 필드 이름과 값은 DNS 제어판마다 다를 수 있지만, 여기서는 가장 일반적인 옵션을 다루었습니다. 확실하지 않은 경우 DNS 공급자에게 확인하십시오.type은 생성하려는 DNS 레코드의 종류입니다. 여기서는 CNAME을 선택해야 합니다.
name 또는 DNS entry는 하위 도메인을 입력하는 위치입니다. 전체 값(예: docs.example.com)을 입력해야 할 수도 있고, 최상위 도메인 앞부분만(예: docs) 입력하면 될 수도 있습니다. 어떤 값을 사용해야 할지 확실하지 않은 경우 DNS 공급자에게 확인하십시오.
target, value 또는 destination은 하위 도메인이 가리켜야 하는 위치입니다. Apidog의 Publish 설정에서 DNS CNAME 옵션을 선택하면 이 값을 확인할 수 있습니다. 이 값은 {projectId}.apidog.io와 유사한 형태입니다. 이 값을 전체로 입력해야 합니다(예: 12345678.apidog.io).
TTL이라는 필드가 표시될 수도 있으며, 이는 Time To Live를 의미합니다. DNS 레코드가 캐시될 수 있는 초 단위 시간입니다. 무엇으로 설정해야 할지 확실하지 않은 경우 Auto를 선택하거나 기본값을 유지하는 것이 좋습니다.
Cloudflare를 사용하고 계십니까?#
Cloudflare 제어판에서 DNS를 구성하는 경우 Cloudflare의 프록시 기능(주황색 구름, 도메인 설정에서 "Proxy status"라고도 함)이 비활성화되어 있는지 확인하십시오. 이는 다음 두 가지 이유 때문입니다.이 옵션은 도메인의 DNS 대상을 공개적으로 난독화하여 Apidog가 사용자 지정 도메인에 대한 정기 점검을 올바르게 실행하지 못하게 합니다.
사용자 지정 도메인은 이미 CDN의 이점을 받게 됩니다.
변경 사항이 적용될 때까지 대기#
간단히 말하면, 다음 단계로 진행하기 전에 DNS 변경 사항이 적용될 때까지 10 minutes ~ 48 hours를 기다려야 할 수 있습니다.앞서 언급한 TTL(Time To Live) 필드를 기억하십니까? DNS 레코드는 일정 기간 동안 캐시됩니다. 일반적으로 DNS 레코드는 자주 변경되지 않기 때문에 성능 측면에서 이는 매우 유용합니다. 하지만 레코드가 변경될 경우, DNS 캐시 서버가 변경 사항을 확인하고 그에 따라 동작하기 전에 캐시가 만료되어야 하는 일정 기간(TTL 값)이 있습니다.대부분의 경우 다음이자 마지막 단계로 진행하기 전에 최소 10분 정도 기다리는 것이 좋습니다. 때로는 조금 더 빠르게 업데이트될 수도 있고, 더 오래 걸릴 수도 있습니다. 48시간보다 오래 걸리는 경우는 드뭅니다._전파(propagation)_라고 하는 이 프로세스가 어떻게 진행되고 있는지 확인하고 싶으십니까? WhatsMyDNS와 같은 DNS 조회 도구를 사용할 수 있습니다. 전체 하위 도메인을 입력하고 드롭다운 목록에서 CNAME을 선택한 다음 Search 버튼을 누르십시오. 전 세계의 DNS 캐시 서버가 캐시된 결과를 알려 줍니다. 대부분의 서버가 할당된 CNAME 값으로 응답할 때까지 이러한 결과를 주기적으로 확인하는 것이 좋습니다.CDN 또는 자체 리버스 프록시 서버 구성하기#
이전 단계에서 Reverse Proxy 옵션을 선택한 경우에만 적용됩니다.
AWS CloudFront를 리버스 프록시로 구성하기#
AWS CloudFront, Cloudflare Enterprise와 같은 클라우드 공급업체에서 제공하는 CDN 서비스를 활용하여 자체 리버스 프록시 서버로 설정할 수 있습니다.다음 예시에서는 AWS CloudFront를 Reverse Proxy로 구성합니다.1.
AWS에 로그인한 다음 CloudFront로 이동하십시오. Create Distribution을 클릭하십시오. 2.
배포 설정을 구성하십시오. 변경해야 하는 값은 다음과 같습니다.
| 설정 | 값 |
|---|
| Origin Domain Name | {projectId}.apidog.io로 설정하십시오 |
| Name | 원본에 대한 설명입니다. 이 값은 동일한 배포 내의 여러 원본을 구분할 수 있게 하므로 고유해야 합니다. |
| Origin Protocol Policy | HTTP Only로 설정하십시오 |
| Alternate Domain Names (CNAMEs) | 사용자 지정 도메인 이름으로 설정하십시오(사용자 지정 도메인 설정 중 Publish 설정에서 구성한 것과 동일한 도메인). |
| SSL Certificate | AWS Certificate Manager(ACM)에 저장된 사용자 지정 도메인의 SSL 인증서로 설정하십시오. |
3.
Origin Custom Headers에 대한 정보를 제공하십시오(Origin Domain Name을 제공한 후에만 Header Name 및 Value 필드가 표시됩니다).
| 헤더 이름 | 값 |
|---|
| X-Apidog-Project-ID | {projectId}로 설정하십시오 |
projectId 값은 Apidog 프로젝트 설정에서 찾을 수 있습니다.
4.
Default Cache Behavior Settings를 구성하십시오. 변경해야 하는 값은 다음과 같습니다.
| 설정 | 값 |
|---|
| Viewer Protocol Policy | Redirect HTTP to HTTPS를 선택하십시오 |
| Allowed HTTP Methods | GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE를 선택하십시오. |
| Cache and origin request settings | Use legacy cache settings를 선택하십시 오. Headers, Query strings 및 Cookies에 대해 All을 선택하십시오. |
5.
AWS **Web Application Firewall (WAF)**을 활성화하지 마십시오.
6.
페이지 하단의 Create distribution을 클릭하십시오. CloudFront Distributions 목록에서 새로 생성된 배포를 확인할 수 있습니다. 배포가 Deployed 상태가 될 때까지 Status는 In progress로 표시됩니다.
7.
사용자 지정 도메인에 대한 DNS에 새 CNAME 레코드를 추가하여 해당 Distribution의 CloudFront Domain Name을 가리키도록 하십시오. 이 값은 Distribution ID를 클릭한 후 General 탭의 Distribution domain name에서 확인할 수 있습니다(예: fd1fbc7cac6197.cloudfront.net).
자체 리버스 프록시 서버 구성하기#
API 문서용으로 자체 리버스 프록시 서버를 구성할 수 있습니다. 다음 예시에서는 Nginx를 리버스 프록시 서버로 사용합니다.1.
간단한 구성을 위해 Nginx 구성 파일에 다음 내용을 추가하십시오.
:8080 {
handle_path /* {
reverse_proxy http://{projectId.apidog.io {
header_up X-Apidog-Project-ID {projectId}
header_up Host "docs.example.com"
}
}
}
}
{projectId} 값은 Apidog 프로젝트 설정에서 찾을 수 있습니다.
2.
사용자 지정 도메인 이름의 DNS 레코드를 구성하여 리버스 프록시 서버를 가리키도록 하십시오.
API 문서를 사용자 지정 도메인의 하위 디렉터리에 배포하기#
구성 단 계:#
1.
Apidog의 Custom Domain 설정 페이지에서 사용자 지정 도메인을 입력하십시오.
2.
Reverse Proxy를 선택하고 Use Subdirectory를 활성화한 다음 하위 디렉터리 경로를 입력하십시오.
3.
다음으로 웹 서버의 구성 파일을 수정해야 합니다. Nginx를 사용하여 서비스를 프록시한다고 가정하면 다음 구성을 참고할 수 있습니다.
proxy_pass: 클라이언트 요청을 다른 서버(예: Apidog의 API 문서 서버)로 전달합니다.
proxy_set_header: 프록시 서버가 업스트림 서버로 보내는 요청 헤더를 설정하여 요청이 올바르게 처리되도록 합니다.
/api-docs/는 사용자 지정 도메인의 하위 디렉터리이며, Nginx 구성에서는 반드시 /로 끝나야 합니다.
http://{projectId}.apidog.io/도 반드시 /로 끝나야 합니다.
{projectId}를 Apidog 프로젝트 ID로 바꾸십시오.
docs.example.com은 사용자 지정 도메인 예시입니다. 실제 사용자 지정 도메인으로 바꾸십시오.
구성 후 서버에서 Nginx를 다시 시작해야 합니다.
HTTPS 활성화하기#
Apidog의 온라인 문서는 HTTPS 프로토콜을 지원하며, 이는 HTTP에 비해 여러 가지 장점이 있습니다.안전한 데이터 전송: HTTPS는 SSL/TLS 암호화를 사용하여 데이터 전송의 보안을 보장하고, 제3자가 정보를 가로채는 것을 방지합니다.
SEO 최적화: 검색 엔진 크롤러는 더 나은 보안 및 개인정보 보호를 제공하기 때문에 HTTPS 사용을 선호합니다. 따라서 HTTPS 웹사이트는 HTTP 웹사이트보다 검색 엔진 순위에서 더 높은 권위를 가질 수 있습니다.
HTTPS 활성화 단계:#
1.
Publish 페이지로 이동하여 Custom Domain 탭을 여십시오.
2.
HTTPS를 켜서 HTTPS를 활성화하고, 선택적으로 통신 탈취 또는 중간자 공격을 방지하기 위해 Always Use HTTPS를 활성화할 수 있습니다.
SSL 인증서 관리#
HTTPS가 활성화되면 SSL 인증서를 관리하는 방법을 선택할 수 있습니다.Generated by Apidog: Apidog가 SSL 인증서를 자동으로 생성합니다.
Use Your Own Certificate: 인증 기관에서 발급한 SSL 인증서와 개인 키를 업로드할 수 있습니다(예: Let's Encrypt). 문제 해결#
사용자 지정 도메인 설정에 문제가 있는 경우 Discord를 통해 문의해 주십시오.Apidog Europe을 사용하고 계십니까?#
Apidog Europe을 사용하는 경우 사용자 지정 도메인 설정에 올바른 도메인을 사용하고 있는지 확인하십시오.이전 설정에서 Apidog Europe의 올바른 도메인은 {projectId}.eu.apidog.com입니다. 
