궁극적인 가이드: 커스텀 도메인에서 API 문서 호스팅하기

소프트웨어 개발의 경쟁이 치열한 세계에서 명확하고 접근 가능한 API 문서를 제공하는 것은 서비스의 원활한 통합과 채택을 가능하게 하는 데 필수적입니다. API 문서의 접근성과 전문성을 향상시키는 효과적인 방법 중 하나는 그것을 맞춤 도메인에 호스팅하는 것입니다. 이 가이드는 맞춤 도메인으로 API 문서를 설정하는 데 필요한 이점과 단계를 안내합니다.

API 문서에 대한 맞춤 도메인의 중요성

API 문서는 귀하의 API에 의존하여 애플리케이션을 구축하는 개발자에게 필수적인 요소입니다. 이 문서를 맞춤 도메인에 호스팅하는 것은 브랜드 아이덴티티를 강화할 뿐만 아니라 사용자에게 사용자 친화적이고 전문적인 경험을 제공합니다. 맞춤 도메인을 사용함으로써 API 문서에 쉽게 접근할 수 있고 귀하의 서비스 품질을 반영할 수 있습니다.

💡

Apidog은 디자인부터 자동 생성 및 호스팅까지 포괄적인 API 문서화를 위한 최고의 플랫폼으로 자리 잡고 있으며, 모든 기능이 Apidog의 무료 버전에서도 제공됩니다. 오늘 사용해 보세요!

button

맞춤 도메인에서 API 문서를 호스팅하는 이점

브랜드 일관성

맞춤 도메인은 API 문서를 브랜드 아이덴티티에 맞춰 정렬할 수 있게 해줍니다. 이를 통해 사용자에게 일관된 경험을 제공하고, 브랜드의 신뢰성 및 전문성을 강화합니다.

향상된 접근성

맞춤 도메인을 사용하면 API 문서에 더 쉽게 기억하고 접근할 수 있습니다. 일반적이거나 긴 URL 대신, 사용자는 브랜드 도메인으로 빠르게 탐색할 수 있어 전반적인 사용자 경험이 향상됩니다.

강화된 보안

맞춤 도메인은 종종 SSL 인증서와 같은 강화된 보안 기능을 제공하여 사용자의 데이터를 보호하고 서비스에 대한 신뢰를 구축합니다. 보안 문서 호스팅은 사용자가 API 문서에 안전하게 접근하고 상호작용할 수 있도록 보장합니다.

SEO 이점

맞춤 도메인은 검색 엔진 순위를 개선할 수 있어 문서가 더 많이 검색될 수 있도록 합니다. API 문서를 검색 엔진에 최적화함으로써 더 많은 개발자를 귀하의 플랫폼으로 유도할 수 있습니다.

맞춤 도메인에서 API 문서를 호스팅하는 단계

1단계. 문서 호스팅 플랫폼 선택

SwaggerHub, Redocly, 그리고 Apidog와 같은 여러 플랫폼이 API 문서를 호스팅할 수 있게 해줍니다. 귀하의 필요에 맞고 맞춤 도메인 구성을 지원하는 플랫폼을 선택하세요.

2단계. 맞춤 도메인 설정

플랫폼을 선택했다면, 맞춤 도메인을 구성하기 위해 다음 일반 단계를 따르세요:

a. 도메인 이름 구매: 아직 도메인이 없다면 GoDaddy, Namecheap 또는 Google Domains와 같은 도메인 등록 대행사에서 구매하세요.

b. DNS 설정 구성: 도메인 등록 대행사에 로그인하고 DNS 관리 섹션으로 이동합니다. 맞춤 도메인이 문서 호스팅 플랫폼의 도메인을 가리키도록 CNAME 레코드를 생성하세요. 예를 들어, 문서가 docs.yourapi.com에 호스팅되는 경우, docs.yourapi.com을 yourapi.docs.hostingplatform.com에 가리키도록 CNAME 레코드를 만듭니다.

c. 도메인 소유 확인: 일부 플랫폼에서는 도메인 소유를 확인해야 합니다. 이 과정은 일반적으로 플랫폼에서 제공된 확인 코드로 DNS 설정에 TXT 레코드를 추가하는 것을 포함합니다.

d. HTTPS(SSL) 구성: 맞춤 도메인이 보안 연결을 위해 HTTPS를 지원하는지 확인합니다. 많은 호스팅 플랫폼이 자동 SSL 인증서를 제공하지만, 경우에 따라 수동으로 구성해야 할 수도 있습니다.

3단계. API 문서 배포

도메인을 구성한 후 문서를 호스팅 플랫폼에 배포합니다. 문서 파일을 업로드하거나 리포지토리에 연결하는 플랫폼별 지침을 따르세요.

4단계. 테스트 및 확인

배포가 완료되면 맞춤 도메인을 통해 API 문서에 접근하여 모든 것이 제대로 작동하는지 확인합니다. 끊어진 링크, 형식 문제 또는 SSL 인증서 오류가 있는지 확인합니다.

Apidog을 사용하여 API 문서 설계, 자동 생성 및 호스팅

디지털 경제에서 API(응용 프로그래밍 인터페이스)는 소프트웨어 애플리케이션 간의 통신을 가능하게 하는 데 중요한 역할을 합니다. 스타트업이든 기업이든, 견고한 API 문서는 개발자가 귀하의 API를 효율적으로 이해하고 사용할 수 있도록 돕는 데 필수적입니다.

모든 API 문서 호스팅 플랫폼 중에서 Apidog는 설계부터 자동 생성 및 호스팅까지 API 문서의 전체 생애 주기를 지원하는 다재다능한 플랫폼으로 돋보입니다. 이 플랫폼이 왜 귀하의 주요 도구가 되어야 하는지 아래에 설명합니다.

1. 포괄적인 API 설계 도구

Apidog는 상세한 API 사양을 작성할 수 있는 강력한 설계 도구를 제공합니다. 처음 시작하든 기존 API를 수정하든 Apidog의 설계 도구는 다음을 제공합니다:

비주얼 인터페이스: API 엔드포인트, 요청/응답 스키마 및 데이터 모델을 설계하기 위한 직관적인 드래그 앤 드롭 인터페이스.
표준 준수: API 설계가 OpenAPI 및 Swagger와 같은 산업 표준을 준수하도록 자동 보장합니다.
협업 설계: 팀원이 실시간으로 협업할 수 있게 하여 API 설계가 집단의 의견에 따라 발전하도록 합니다.

2. 문서 자동 생성

Apidog의 두드러진 기능 중 하나는 API 사양에서 직접 API 문서를 자동 생성할 수 있는 기능입니다. 이를 통해 문서가 항상 최신 상태로 유지되고 API의 현재 상태와 일치합니다.

동기화: API 설계를 변경할 때마다 문서가 자동으로 업데이트됩니다.
풍부한 문서: 상세한 설명, 데이터 모델, 예제 요청 및 응답, 인증 방법을 포함합니다.
맞춤화: 마크다운, 코드 예제, 메타데이터를 사용하여 문서를 향상시킬 수 있는 사용자 정의 메모를 추가할 수 있습니다.

3. 상호작용 API 문서

Apidog는 상호작용 문서를 지원하여 개발자가 문서에서 직접 API 엔드포인트를 테스트할 수 있게 해 줍니다. 이 실습 기능은 개발자 경험을 향상시키고 귀하의 API를 채택하고 사용할 가능성을 높입니다:

Try-It-Out 기능: 개발자가 온라인 문서 내에서 API 요청을 실행하고 응답을 직접 볼 수 있게 합니다.
인증 처리: API 키, 토큰 및 기타 인증 방법을 원활하게 관리합니다.

4. 쉬운 호스팅과 맞춤 도메인

Apidog는 문서 설계 및 생성뿐만 아니라 강력한 호스팅 솔루션도 제공합니다. 귀하의 문서를 맞춤 도메인에 호스팅할 수 있어 브랜드의 전문성을 높이고 자원을 중앙집중화할 수 있습니다.

맞춤 도메인: 브랜드와 일치하는 도메인(예: docs.yourcompany.com)에 문서를 호스팅합니다.
보안: 문서를 안전하게 유지하기 위해 SSL 암호화, 사용자 인증 및 권한 관리를 제공합니다.

5. 개발 도구와의 원활한 통합

Apidog는 다양한 개발 및 CI/CD 도구와 원활하게 통합되어 워크플로우를 간소화합니다. 이러한 호환성은 귀하의 문서가 더 넓은 개발 생애 주기의 일부가 되도록 보장합니다:

버전 관리 시스템: GitHub, GitLab 및 Bitbucket과 통합됩니다.
CI/CD 파이프라인: Jenkins, CircleCI 및 기타 CI/CD 도구와 호환됩니다.

6. 강력한 협업 기능

팀의 경우, 협업은 정확하고 포괄적인 문서를 유지하는 데 핵심입니다. Apidog는 여러 협력자를 지원하고 변경 사항이 효율적으로 추적되고 관리되도록 하는 기능을 제공합니다:

실시간 편집: 여러 팀원이 동시에 문서 작업을 할 수 있습니다.
버전 관리: 변경 사항을 추적하고 이전 버전으로 되돌리며 문서 업데이트를 원활하게 관리합니다.

API 문서를 위한 맞춤 도메인 설정

Apidog에서는 API 문서를 위해 맞춤 도메인을 사용할 수 있는 기능을 제공합니다. 이를 수행하는 방법에 대한 단계별 가이드는 다음과 같습니다:

1단계. 맞춤 도메인 설정 시작

맞춤 도메인은 소유자 또는 관리자 접근 권한이 있는 사용자가 구성할 수 있습니다. 시작하려면 다음 단계를 따르세요:

1. 공유 모듈 접근

Apidog에서 프로젝트의 공유 모듈로 이동합니다.

사이드바에서 문서 공유 메뉴를 클릭합니다.
보조 메뉴에서 발행 설정 페이지로 이동합니다.

2. 맞춤 도메인 설정 시작

맞춤 도메인 섹션에서 편집 버튼을 클릭합니다.

맞춤 도메인 설정을 위한 두 가지 옵션을 볼 수 있습니다:

CNAME: 단순성과 유연성 때문에 권장됩니다.
리버스 프록시: 더 고급 기능으로, CDN이나 리버스 프록시 설정에 익숙한 사용자에게 적합합니다.

2단계. API 문서를 위한 맞춤 도메인 설정

방법 1: CNAME을 사용한 맞춤 도메인 설정

1. CNAME 레코드 설정

DNS 구성을 위해 DNS 제공업체의 제어판에서 작업을 수행합니다. 일반적인 절차는 다음과 같습니다:

유형: CNAME 선택.
이름 또는 DNS 항목: 서브도메인 입력(예: docs.example.com 또는 도메인이 암시되는 경우 단순히 docs).
대상 또는 값 또는 목적지: 이 서브도메인으로 안내해야 하는 위치로, CNAME 옵션을 선택할 때 Apidog의 발행 설정에서 찾을 수 있습니다. 다음과 같은 형식으로 나타납니다: {projectId}.apidog.io (예: 12345678.apidog.io).
TTL(유효 시간): 자동으로 설정하거나 불확실한 경우 기본값을 유지합니다.

선택한 서브도메인에 대해 A, AAAA, TXT와 같은 충돌하는 레코드가 존재하지 않도록 하세요. CNAME 레코드를 추가하기 전에 필요할 경우 이러한 레코드를 제거하십시오.

Cloudflare 사용자에 대한 특별한 참고 사항:

Cloudflare를 사용하는 경우:

Cloudflare의 프록시 설정이 비활성화되어 있는지 확인합니다.
이 설정은 DNS 대상 격리를 방지하고 Apidog이 정기적인 도메인 확인 작업을 수행할 수 있도록 해줍니다.

2. DNS 전파 대기

DNS 변경 사항은 일반적으로 10분에서 48시간 사이에 전파됩니다. 진행 상황을 추적하려면 WhatsMyDNS와 같은 DNS 조회 도구를 사용할 수 있습니다. 서브도메인을 입력하고 CNAME을 선택한 후 검색 버튼을 눌러 실시간 전달 업데이트를 확인하세요.

방법 2: 웹 서버를 사용하여 맞춤 도메인 설정

이 단계는 리버스 프록시 옵션을 선택한 경우에 해당합니다.

리버스 프록시 서버를 설정하는 사용자의 경우, Nginx를 설정하는 방법은 다음과 같습니다:

1. Nginx 설정:

server {
    ...
    location / {
        proxy_pass  http://{projectId}.apidog.io;
        proxy_set_header X-Apidog-Project-ID {projectId};
        proxy_set_header Host docs.example.com;
        ...
    }
    ...
}

Caddy 설정 예:

:8080 {
        handle_path /* {
                reverse_proxy http://{projectId.apidog.io {
                        header_up X-Apidog-Project-ID {projectId}
                        header_up Host "docs.example.com"
                }

      }
}
}

2. DNS 레코드 설정:

맞춤 도메인 이름에 대한 DNS 레코드를 구성하여 리버스 프록시 서버를 가리키도록 설정합니다.

방법 3: CDN을 사용하여 맞춤 도메인 설정

이 단계는 리버스 프록시 옵션을 선택한 경우에 해당합니다.

1. AWS CloudFront를 리버스 프록시로 설정

AWS CloudFront 또는 다른 CDN 서비스를 리버스 프록시 서버로 사용할 수 있습니다. 이 예에서는 AWS CloudFront를 리버스 프록시 서버로 사용할 것입니다.

AWS에 로그인하고 CloudFront로 이동합니다. 배포 생성을 클릭합니다.

배포 설정을 구성합니다:

원본 도메인 이름: {projectId}.apidog.io
이름: 원본에 대한 설명으로, 고유해야 하며, 같은 배포 내에서 여러 원본을 구분할 수 있게 해줍니다.
원본 프로토콜 정책: HTTP만 설정합니다.
대체 도메인 이름(CNAME): 귀하의 맞춤 도메인 이름입니다.
SSL 인증서: AWS 인증서 관리자(ACM)에서 SSL 인증서를 선택합니다.

원본 사용자 정의 헤더:

헤더 이름: X-Apidog-Project-ID
값: {projectId}

기본 캐시 동작 설정:

보는 프로토콜 정책: HTTP를 HTTPS로 리다이렉트합니다.
허용된 HTTP 메서드: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE를 선택합니다.
캐시 및 원본 요청 설정: 레거시 캐시 설정을 사용하고, 헤더, 쿼리 문자열 및 쿠키에 대해 모두 선택합니다.

2. 배포 완료:

페이지 하단에서 배포 생성를 클릭합니다. 배포 상태는 배포될 때까지 "진행 중"으로 표시됩니다.

3. DNS 설정:

CloudFront 도메인 이름을 가리키도록 DNS 제공업체의 제어판에 CNAME 레코드를 추가합니다.

웹사이트의 하위 디렉토리에 API 문서 포함하기

Apidog 버전 ≥ 2.5.24에서 사용할 수 있습니다. API 문서를 하위 디렉토리(예: Your-Website.com/api-docs)에 포함할 수 있습니다.

1. Apidog에서 리버스 프록시 활성화:

맞춤 도메인 설정으로 이동합니다.
리버스 프록시를 클릭하고 하위 디렉토리 사용를 활성화합니다.

2. 웹 서버(Nginx 등) 설정 수정:

server {
    ...
    location /api-docs/ {
        proxy_pass  http://{projectId}.apidog.io/;
        proxy_set_header X-Apidog-Project-ID {projectId};
        proxy_set_header Host docs.example.com;
        ...
    }
    ...
}

API 문서에 대한 모범 사례

일관된 브랜딩: 맞춤 도메인과 API 문서의 내용을 브랜드 스타일 및 메시지와 일치하도록 하세요.
포괄성 유지: 상세한 설명, 코드 예제 및 사용 사례를 포함하세요.
명확한 탐색 제공: 문서가 명확한 구조와 검색 기능으로 쉽게 탐색할 수 있도록 하십시오.
정기적 업데이트: 문서가 최신 API 변경 사항 및 향상된 사항을 반영하도록 업데이트하세요.
모니터링: 사용자 경험이 원활하게 유지되도록 정기적으로 맞춤 도메인을 모니터링하여 문제나 다운타임을 확인하세요.
사용자 피드백: 사용자에게 문서에 대한 피드백을 제공하도록 권장하여 명확성과 사용성을 지속적으로 개선하세요.

결론

소프트웨어 개발의 경쟁이 치열한 분야에서 명확하고 접근 가능한 API 문서를 제공하는 것은 서비스의 원활한 통합과 채택에 매우 중요합니다. 맞춤 도메인에서 API 문서를 호스팅하는 것은 브랜드 일관성 향상, 접근성 개선, 보안 증가 및 SEO 성능 향상 등 다양한 이점을 제공합니다. 이 가이드에서 설명한 단계를 따르면 API 문서를 맞춤 도메인에서 쉽게 설정하고 배포할 수 있으므로 사용자 경험을 향상시키고 브랜드 전문성을 강화할 수 있습니다.

Apidog과 같은 플랫폼은 설계, 자동 생성 및 API 문서 호스팅을 위한 종합적인 도구를 제공하여 이 프로세스를 더욱 간단하게 만들어 줍니다. 강력한 설계 인터페이스, 상호작용 문서화, 개발 도구와의 원활한 통합 및 강력한 협업 기능과 같은 기능을 제공하는 Apidog는 API 문서 관리 요구를 위한 다재다능한 솔루션으로 두드러집니다.

결국, API 문서를 위한 맞춤 도메인에 투자하는 것은 서비스에 대한 인식을 제고할 뿐만 아니라 개발자가 귀하의 API에 효율적으로 접근하고 활용할 수 있도록 보장합니다. 품질 문서화를 우선시하고 Apidog와 같은 도구를 활용함으로써 개발자 커뮤니티와의 신뢰 및 참여를 증진할 수 있으며, API의 성공과 채택을 이끌어낼 수 있습니다.