전문적인 API 문서에는 전문적인 도메인이 필요합니다. 기본적으로 Apidog 문서는 <subdomain>.apidog.io 도메인에서 접근할 수 있습니다. 그러나 자체 도메인을 설정하여 이를 사용자 지정할 수 있으며, 이를 통해 사용자가 조직의 브랜딩에 부합하는 도메인에서 문서에 접근할 수 있습니다.사전 요구 사항#
사용자 지정 도메인을 설정하기 전에 다음 사항을 갖추었는지 확인하십시오.(역방향 프록시 방법의 경우) CDN 또는 역방향 프록시 구성에 대한 이해
사용자 지정 도메인 설정 시작하기#
사용자 지정 도메인 설정에 접근하려면 사이드바의 Publish Docs 메 뉴로 이동한 다음 Publish 설정 페이지로 이동하십시오. Custom Domain 섹션에서 Edit 버튼을 클릭하여 설정을 시작할 수 있습니다.사용자 지정 도메인 설정 방법#
사용자 지정 도메인을 설정하는 옵션에는 두 가지 유형이 있습니다.1.
CNAME(권장): 설정 및 유지 관리가 가장 쉬우며, 서브도메인과 루트 도메인 모두에서 작동하여 최대한의 유연성을 제공합니다.
2.
역방향 프록시(고급): 콘텐츠 전송 네트워크(CDN)를 사용하거나 자체 서버에 역방향 프록시를 설정해야 하며, 이러한 기술에 익숙한 사용자에게 권장됩니다.
CNAME 구성하기#
이 섹션은 이전 단계에서 CNAME 옵션을 선택한 경우에만 적용됩니다.
CNAME 레코드 구성하기#
DNS 제어판마다 필드 이름과 구성 단계가 다를 수 있지만, 핵심 개념은 동일합니다. 확실하지 않은 경우 DNS 제공업체에 확인하십시오.type은 생성하려는 DNS 레코드의 종류입니다. 여기서는 CNAME을 선택해야 합니다.
name 또는 DNS entry는 서브도메인을 입력하는 위치입니다. 전체 주소(예: docs.example.com)를 입력해야 할 수도 있고, 최상위 도메인 앞부분만(예: docs) 입력하면 될 수도 있습니다. 어느 것을 사용해야 할지 확실하지 않은 경우 DNS 제공업체에 확인하십시오.
target, value 또는 destination은 서브도메인이 가리켜야 하는 위치입니다. Apidog에서 DNS CNAME 옵션을 선택하면 Publish 설정에서 이 값을 확인할 수 있습니다. 값은 {docsSiteId}.apidog.io와 유사한 형태입니다. 이 값을 전체로 입력해야 합니다(예: 12345678.apidog.io).
TTL이라는 필드가 보일 수도 있으며, 이는 Time To Live를 의미합니다. DNS 레코드를 캐시할 수 있는 시간(초)입니다. 무엇으로 설정해야 할지 확실하지 않은 경우 Auto를 선택하거나 기본값을 유지하는 것이 좋습니다.
CNAME 레코드는 동일한 이름에 대한 다른 레코드와 공존할 수 없습니다. 선택한 서브도메인에 대해 이미 A 레코드, AAAA 레코드, TXT 레코드 또는 다른 유형의 레코드가 있는 경우, CNAME 레코드를 추가하기 전에 먼저 해당 레코드를 제거해야 합니다.
Cloudflare 제어판에서 DNS를 구성하는 경우, Cloudflare의 프록 시 기능(주황색 구름 아이콘, 도메인 설정에서 "Proxy status"라고도 함)이 비활성화되어 있는지 확인하십시오. 그 이유는 두 가지입니다.이 옵션은 도메인의 DNS 대상을 공개적으로 난독화하여 Apidog가 사용자 지정 도메인에 대한 정기 검사를 제대로 수행하지 못하게 합니다.
사용자 지정 도메인은 이미 CDN의 이점을 받게 됩니다.
변경 사항이 적용되는 데 얼마나 걸립니까?#
간단히 말하면, 다음 단계로 진행하기 전에 DNS 변경 사항이 적용될 때까지 10분에서 최대 48시간까지 기다려야 할 수 있습니다.앞서 언급한 TTL(Time To Live) 필드를 기억하십니까? DNS 레코드는 일정 시간 동안 캐시됩니다. 일반적으로 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를 역방향 프록시로 구성합니다.1.
AWS에 로그인하고 CloudFront로 이동하십시오. Create Distribution을 클릭하십시오. 2.
배포 설정을 구성하십시오. 변경해야 할 값은 다음과 같습니다.
| 설정 | 값 |
|---|
| Origin Domain Name | {docsSiteId}.apidog.io로 설정 |
| Name | 오리진에 대한 설명입니다. 이 값은 동일한 배포 내의 여러 오리진을 구분할 수 있게 해 주므로 고유해야 합니다. |
| Origin Protocol Policy | HTTP Only로 설정 |
| Alternate Domain Names (CNAMEs) | 사용자 지정 도메인 이름으로 설정합니다(사용자 지정 도메인 설정 중 Publish 설정에서 구성한 것과 동일한 도메인). |
| SSL Certificate | AWS Certificate Manager(ACM)에 저장된 사용자 지정 도메인의 SSL 인증서로 설정합니다. |
3.
Origin Custom Headers에 대한 정보를 제공하십시오(Header Name 및 Value 필드는 Origin Domain Name을 제공한 후에만 표시됩니다).
| 헤더 이름 | 값 |
|---|
| X-Apidog-Docs-Site-ID | {docsSiteId}로 설정 |
{docsSiteId}는 사용자 지정 도메인 패널에서 확인할 수 있는 Docs Site ID입니다. 올바른 ID를 입력했는지 반드시 확인하십시오.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 레코드를 추가하여 배포의 CloudFront Domain Name을 가리키도록 하십시오. 이는 Distribution ID를 클릭한 후 General 탭의 Distribution domain name에서 확인할 수 있습니다(예: fd1fbc7cac6197.cloudfront.net).
Cloudflare를 역방향 프록시로 구성하기#
Cloudflare Workers를 사용하여 역방향 프록시로 작동하게 할 수 있습니다. 이를 통해 도메인을 프록시 상태(Orange Cloud)로 유지하면서 Apidog가 필요한 프로젝트 식별자를 수신하도록 할 수 있습니다.2.
Create Application을 클릭한 다음 Create Worker를 클릭하십시오. (방법을 선택하라는 메시지가 표시되면 **Start with Hello World!**로 계속 진행하십시오.)
3.
Worker 이름을 지정하고(예: apidog-docs-proxy) Deploy를 클릭하십시오.
4.
Edit Code를 클릭하고 기존 스크립트를 다음으로 교체하십시오.
사용자 지정 도메인 패널에서 {docsSiteId}를 확인할 수 있습니다. targetHost 및 docsSiteId 변수 모두에 올바른 ID를 입력했는지 반드시 확인하십시오.
6.
Worker의 Settings 탭으로 이동하여 Domains & Routes를 선택한 다음 +Add 버튼을 클릭하십시오.
7.
사용자 지정 도메인을 입력하십시오(예: docs.example.com). Cloudflare가 DNS 레코드와 SSL 인증서를 자동으로 처리합니다.
8.
Cloudflare와 Apidog 간의 보안 통신을 허용하려면 Cloudflare SSL/TLS encryption mode가 Full 또는 **Full (Strict)**로 설정되어 있는지 확인하십시오.
Worker에 사용자 지정 도메인을 연결하기 전에 해당 도메인(예: example.com)이 이미 Cloudflare 계정에 추가되어 있고 네임서버가 활성 상태인지 확인하십시오.
자체 역방향 프록시 서버 구성하기#
API 문서용 자체 역방향 프록시 서버를 구성할 수 있습니다. 다음 예시에서는 Nginx를 역방향 프록시 서버로 사용합니다.1.
간단한 구성을 위해 다음 내용을 Nginx 구성 파일에 추가하십시오.
:8080 {
handle_path /* {
reverse_proxy http://{docsSiteId}.apidog.io {
header_up X-Apidog-Docs-Site-ID {docsSiteId}
header_up Host "docs.example.com"
}
}
}
{docsSiteId}는 사용자 지정 도메인 패널에서 확인할 수 있는 Docs Site ID입니다. 올바른 ID를 입력했는지 반드시 확인하십시오.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://{docsSiteId}.apidog.io/도 반드시 /로 끝나야 합니다.
{docsSiteId}를 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 인증서를 관리하는 방법을 선택할 수 있습니다.Apidog에서 생성: Apidog가 SSL 인증서를 자동으로 생성합니다.
자체 인증서 사용: 인증 기관에서 발급한 SSL 인증서와 개인 키를 업로드할 수 있습니다(예: Let's Encrypt). 문제 해결#
사용자 지정 도메인 설정에 문제가 있는 경우 Discord를 통해 문의해 주십시오.Apidog Europe을 사용하고 계십니까?#
Apidog Europe을 사용 중인 경우, 사용자 지정 도메인 설정에 올바른 도메인을 사용하고 있는지 확인하십시오.이전 설정에서 Apidog Europe의 올바른 도메인은 {docsSiteId}.eu.apidog.com입니다. 
