안녕하세요, 평소에 QA 엔지니어로 일하고 있는 개발자입니다. 최근에 제가 작성한 API 문서가 검색 엔진에 전혀 노출되지 않아 고민이었습니다. 아무리 내용을 꼼꼼하게 작성해도 Google에서 관련 키워드를 검색해도 제 문서가 나오지 않았습니다... 이건 정말 실망스러운 일이죠.
사실 문제는 내용이 아니라 SEO 최적화가 부족했던 것입니다. 이번에는 Apidog을 사용하여 API 문서의 SEO 설정을 철저히 최적화하는 방법을 소개하겠습니다. 직접 시도해 본 결과 검색 순위가 상당히 올라갔으니, 같은 고민을 가진 분들에게 도움이 되었으면 합니다.
Apidog의 기본 최적화 기능
먼저 알아두어야 할 것은, Apidog으로 공개하는 온라인 문서에는 기본적으로 몇 가지 SEO 대책이 적용되어 있습니다. 구체적으로는:
- 사이트맵(sitemap) 자동 생성
- robots.txt 파일 관리
- 의미 있는 URL 구조
- 페이지별 커스터마이징 가능한 메타데이터 태그
이것들은 검색 엔진이 사이트를 크롤링하고 인덱싱할 때 매우 중요한 요소입니다. 하지만 여기서 더 세밀하게 설정함으로써 검색 결과에서의 노출 순위를 크게 개선할 수 있습니다.
페이지 레벨 SEO 설정부터 시작하기
Apidog에서는 개별 페이지 레벨과 사이트 전체 레벨, 두 가지 레이어에서 SEO 설정이 가능합니다. 먼저 개별 페이지 설정부터 살펴보겠습니다.
모든 API 문서나 Markdown 페이지의 오른쪽 상단에 "SEO 설정" 아이콘이 있습니다. 이를 클릭하면 설정 패널이 열립니다. 솔직히 처음에는 "이런 세밀한 설정이 필요할까?"라고 생각했지만, 실제로 설정해보니 효과가 매우 컸습니다.
커스텀 URL 설정
가장 기본적인 것은 커스텀 URL 기능입니다. 시스템이 기본적으로 생성하는 URL에는 숫자 나열이 포함되어 있어, 예를 들면 https://{your-domain.com}/5702007m0와 같습니다. 이렇게 되면 어떤 페이지인지 전혀 알 수 없죠.
예를 들어 "반려동물 정보 조회" API의 URL을 get-pet-info로 설정하면, 최종 주소는 https://{your-domain.com}/get-pet-info가 됩니다. 한눈에 기능을 알 수 있어 사용자에게도 검색 엔진에게도 친절합니다.
메타 타이틀과 메타 디스크립션
Meta Title과 Meta Description 설정도 중요합니다. Meta Title은 검색 결과에 표시되는 파란색 제목 부분으로, 검색 랭킹과 클릭률에 직접적인 영향을 미칩니다.
개인적으로는 제목에 반드시 주요 키워드를 넣는 것을 권장합니다. 예를 들어 "Apidog - 반려동물 정보 조회 API 명세서"와 같이요. 이것만으로도 검색 순위가 달라질 수 있습니다.
Meta Description은 페이지 설명문으로, 검색 엔진이 이를 검색 결과에 표시하기도 합니다. 여기에도 중요한 키워드를 자연스럽게 넣어두면 효과적입니다.
키워드와 커스텀 메타데이터
Keywords 설정도 잊지 마세요. 최근 검색 엔진은 keywords에 대한 의존도가 낮아졌지만, 페이지 주제 이해에는 도움이 됩니다. "반려동물 정보 조회" API라면 "반려동물 정보, API, REST API, 데이터 조회" 등이 좋을 것입니다.
더 고급 SEO 요구사항이 있는 경우, "커스텀 Metadata" 기능을 사용하여 임의의 meta 태그를 추가할 수 있습니다. JSON 형식으로 설정하므로 처음에는 조금 어색할 수 있지만, 익숙해지면 매우 편리합니다. 예를 들면:
{"name": "robots", "content": "noindex"}이렇게 하면 특정 페이지를 검색 엔진 인덱스에서 제외할 수 있습니다. 또한:
{"property": "og:image", "content": "이미지 링크"}이렇게 하면 SNS에서 공유될 때 썸네일 이미지를 설정할 수 있습니다.
사이트 전체 SEO 설정
개별 페이지 설정이 끝났다면, 다음은 사이트 전체 설정입니다. 온라인 문서를 공개할 때 "SEO 설정" 모듈에서 관리할 수 있습니다.
글로벌 메타데이터 설정
글로벌 Metadata는 가장 중요한 기능 중 하나입니다. 사이트 전체에 적용되는 공통 meta 태그를 설정할 수 있으며, 모든 페이지가 이러한 설정을 상속받습니다. 더 중요한 것은 내부 변수를 지원하므로 페이지마다 같은 정보를 반복해서 입력할 필요가 없다는 점입니다.
예를 들면:
[
{"property": "og:title", "content": "{{PAGE_TITLE}} - {{SITE_NAME}}"}
]여기서 {{PAGE_TITLE}}과 {{SITE_NAME}}은 실제 페이지 제목과 사이트 이름으로 자동 대체됩니다. 이는 정말 편리해서, 한 번 설정하면 이후에는 자동으로 최적의 메타데이터가 생성됩니다.
설정에는 우선순위가 있습니다: 페이지 레벨 설정 > 글로벌 설정 > 시스템 기본값. 이 계층 구조 덕분에 유연성을 유지하면서 설정 충돌을 피할 수 있습니다.
robots.txt와 sitemap.xml 관리
robots.txt 파일 관리도 간단합니다. 이 파일은 검색 엔진 크롤러에 대한 지침서와 같은 것으로, 어떤 페이지를 크롤링해도 되는지 알려줍니다. Apidog은 기본적인 robots.txt를 자동 생성하여 모든 크롤러가 모든 페이지에 접근할 수 있게 하고, sitemap 파일의 위치도 지정합니다.
sitemap.xml 기능은 기본적으로 활성화되어 있습니다. 이는 SEO에 매우 도움이 되기 때문입니다. 이 파일은 사이트의 목차와 같은 것으로, 모든 페이지의 주소를 나열합니다. 검색 엔진 크롤러는 이 목차가 있으면 더 체계적이고 효율적으로 콘텐츠를 크롤링할 수 있습니다. 활성화하면 https://{your-domain.com}/sitemap.xml에서 접근할 수 있습니다.
리다이렉트 규칙 설정
공개된 문서의 URL을 변경해야 할 경우, "문서 리다이렉트 규칙" 기능이 유용합니다. 예를 들어 문서 주소를 변경하거나 주소 구조를 최적화하는 경우, URL을 직접 변경하면 사용자가 이전 주소로 접근할 때 404 오류가 표시됩니다.
리다이렉트 규칙을 설정하면 이전 주소로 접근한 사용자를 자동으로 새 주소로 리다이렉트할 수 있습니다. 이를 통해 사용자 경험을 유지하면서 SEO 평가 하락도 방지할 수 있습니다. URL을 변경할 때는 항상 리다이렉트를 설정하는 것이 좋습니다.
URL 명명의 두 가지 전략
URL 설정에 관해서는 커스텀 URL을 설정했는지 여부에 따라 시스템이 다른 전략을 채택합니다. 커스텀 URL을 설정한 경우, 시스템은 그 값을 직접 사용합니다. 예를 들어 api-overview로 설정하면 최종 주소는 https://{your-domain.com}/api-overview가 됩니다.
커스텀 URL을 설정하지 않은 경우, 시스템은 두 가지 자동 생성 규칙을 제공합니다:
-
제목과 ID의 조합: 예를 들어
https://{your-domain.com}/SEO-설정-5702007m0. 이 방법은 의미 정보를 포함하면서 고유성도 보장합니다. -
ID만: 예를 들어
https://{your-domain.com}/5702007m0. 더 단순하지만 의미 정보가 부족합니다.
SEO 관점에서는 첫 번째 방법이 유리합니다. 검색 엔진이 URL의 키워드를 랭킹 요소 중 하나로 사용하기 때문입니다. 다만, 문서 사이트의 권위성이나 인지도가 충분히 높은 경우에는 URL의 의미성 중요도가 상대적으로 낮아집니다.
경험상, 대부분의 문서 사이트에서는 키워드를 포함한 URL을 선택하는 것이 좋습니다. 단순함을 중시하거나 문서 구조가 복잡한 경우에는 두 번째 방법도 합리적인 선택입니다.
실용적인 설정 조언
실제 운영에서는 먼저 글로벌 설정부터 시작하는 것이 좋습니다. 글로벌 Metadata를 설정하고 문서 사이트 전체의 SEO 기반을 구축합니다. 이 단계가 완료되면 모든 페이지에 기본적인 SEO 설정이 적용됩니다.
그 후, 특히 트래픽을 얻고 싶은 중요한 페이지에 초점을 맞춥니다. 예를 들어, 가장 많이 사용되는 API 인터페이스나 신규 사용자가 처음 접하는 퀵 스타트 문서 등입니다. 이러한 페이지에는 개별적으로 페이지 레벨 최적화를 수행하여 더 정확한 제목, 설명, 키워드를 설정합니다.
URL 규칙 선택에 관해서는, 팀이 SEO 효과를 중시한다면 제목을 포함한 URL 규칙을 선택하는 것이 좋습니다. 단순함을 중시한다면 ID만 있는 규칙을 선택할 수 있습니다.
주의할 점은 SEO는 장기적인 프로세스이므로 설정 후 즉시 효과가 나타나기를 기대하지 마세요. 검색 엔진 랭킹은 페이지 자체의 최적화뿐만 아니라 사이트 전체의 권위성, 다른 사이트에서의 링크(백링크), 사용자 행동 데이터 등 많은 요인에 영향을 받습니다.
페이지 레벨과 사이트 레벨 모두에서 SEO를 최적화해도 검색 엔진이 변경을 인식하고 평가하는 데 약 1개월이 걸렸습니다. 인내심을 갖고 기다리는 것이 중요합니다.
요약
Apidog의 완전한 SEO 기능을 활용하면 API 문서가 검색 엔진에서 더 좋은 결과를 얻을 수 있습니다. 페이지 레벨의 세밀한 최적화부터 사이트 레벨의 통합 관리까지, 커스텀 URL부터 메타데이터 설정, 사이트맵 생성부터 리다이렉트 규칙까지, 이러한 기능들은 문서 사이트 SEO의 모든 측면을 다룹니다.
이러한 설정을 한 후, API 문서의 검색 순위가 크게 향상되고 사용자 피드백도 증가했습니다. 특히 커스텀 URL과 메타 타이틀 최적화가 효과적이었다고 느꼈습니다.
더 자세한 정보는 Apidog 도움말 문서의 SEO 설정 모듈을 참조하세요. 또한, 검색 엔진 최적화에 대해 더 배우고 싶은 분들은 다음 리소스를 추천합니다:
마지막으로, 여러분의 API 문서 SEO 설정 경험이나 질문이 있으면 댓글로 공유해 주세요. 함께 배우고 성장해 나가요!
