Kong은 마이크로서비스 아키텍처를 위한 API 게이트웨이 솔루션으로, 다양한 플러그인과 연동하여 HTTP 요청을 라우팅하고 관리할 수 있는 기능을 제공합니다. 이 프로젝트는 Kong의 공식 문서 웹사이트를 위한 아카이브 레포지토리로, 사용자들이 Kong 플랫폼을 효과적으로 활용할 수 있도록 돕기 위해 개발되었습니다. 이 글에서는 Kong의 문서 웹사이트를 어떻게 활용할 수 있는지, 그리고 이를 통해 API 관리의 새로운 가능성을 어떻게 열 수 있는지에 대해 알아보겠습니다.

Kong 문서 웹사이트의 주요 기능

Kong의 문서 웹사이트는 Jekyll 기반으로 구축되어 있으며, 다음과 같은 주요 기능을 제공합니다:

  1. 초보자 친화적: 문서 작성에 익숙하지 않은 개발자나 기술 작가도 쉽게 참여할 수 있도록 다양한 가이드를 제공합니다. 초보자를 위한 good first issue가 라벨링된 문제들이 있어 기여가 용이합니다.
  2. 커뮤니티 중심: 문서 기여를 통해 커뮤니티와 소통하며, 여러분의 의견이 반영될 수 있는 기회를 제공합니다.
  3. 로컬 환경에서의 테스트: 개발자는 로컬 환경에서 문서를 빌드하고 테스트할 수 있는 기능을 제공합니다.
  4. 버전 관리: 다양한 제품과 버전에 대한 문서를 관리할 수 있으며, 특정 제품과 버전만을 선택적으로 빌드할 수 있는 기능이 있습니다.

설치 및 사용 방법

Kong 문서 웹사이트를 로컬 환경에서 사용해 보려면 다음의 단계를 따라주세요.

1. 레포지토리 클론하기

먼저 GitHub에서 레포지토리를 클론합니다:

git clone https://github.com/Kong/docs.konghq.com.git
cd docs.konghq.com

2. 의존성 설치

Makefile을 사용하여 필요한 의존성을 설치합니다:

make install

3. 환경 파일 설정

.env.example 파일을 복사하여 .env 파일을 생성하고, 필요한 환경 변수를 설정합니다: 
cp .env.example .env
# .env 파일을 열고 필요한 값들을 설정합니다.

4. 문서 빌드 및 실행

로컬 서버에서 문서를 빌드하고 실행하려면 다음 명령어를 사용하세요:

make run

이제 웹 브라우저에서 http://localhost:8888로 접속하면 로컬 환경에서 실행 중인 문서 웹사이트를 확인할 수 있습니다.

5. 특정 제품 및 버전 빌드

전체 문서 사이트를 빌드하는 것이 시간이 오래 걸리므로, 특정 제품과 버전만을 선택적으로 빌드할 수 있습니다. 다음의 형식을 사용하여 환경 변수를 설정합니다:

KONG_PRODUCTS='gateway:2.8.x;3.3.x,mesh:2.2.x,hub' make run

위 명령어를 실행하면, 특정 버전의 Gateway 및 Mesh 문서와 플러그인 허브가 생성됩니다.

실무에서의 활용 시나리오

Kong 문서 웹사이트는 실제 프로젝트에서 API 문서를 관리하는 데 유용하게 활용될 수 있습니다. 예를 들어, 새로운 API를 추가하거나 기존 API의 변경사항을 문서화할 때, 로컬 환경에서 문서를 수정하고 테스트한 후, GitHub에 Pull Request를 통해 변경사항을 쉽게 반영할 수 있습니다.

또한, 다양한 플러그인에 대한 문서를 작성하거나 업데이트할 때, Issues 탭에서 good first issue로 표시된 항목을 찾아 기여할 수 있습니다. 이는 팀 내외부의 커뮤니케이션을 활성화하고, 문서 품질을 높이는 데 기여할 수 있습니다.

비슷한 도구와 비교

Kong 외에도 API 문서화 도구로는 Swagger, Postman 등이 있습니다. Swagger는 API 문서를 자동으로 생성해주는 기능이 강력하며, Postman은 API 테스트와 문서화 기능을 통합하여 제공하는 도구입니다. 그러나 Kong의 문서 웹사이트는 Jekyll을 기반으로 하여 커스터마이징이 용이하고, GitHub와의 통합이 강력하여 팀 내 기여가 수월한 장점을 가지고 있습니다.

마무리 및 추천 대상

Kong의 문서 웹사이트는 API 관리와 문서화에 관심 있는 개발자, 기술 작가, 그리고 팀원들과의 협업을 원활하게 하고 싶은 모든 이들에게 추천합니다. 문서화에 대한 경험이 적더라도 친절한 가이드라인 덕분에 쉽게 기여할 수 있습니다.

자세한 내용은 GitHub 레포지토리에서 확인해 보세요: Kong/docs.konghq.com