SmartDocs API 참조 문서 외에 API 사용자를 위해 커스텀 문서를 포털에 추가할 수 있습니다. 사용자들에게 추가 문서 페이지를 제공할 필요가 없더라도 API 사용 방법을 설명하기 위해 포털에 표시되는 시작 가이드 예시를 업데이트해야 합니다.
이 페이지는 시작 가이드 예시 변경 방법과 포털용 추가 문서 페이지 생성 및 표시 방법을 설명합니다. 각 작업에 대해 작업 완료에 필요한 최소한의 ID 및 액세스 관리 역할이 제공됩니다. IAM 권한에 대한 자세한 내용은 다음을 참조하세요.
기본 요건
이 페이지는 아래 작업을 이미 완료했다고 가정합니다.
커스텀 문서 정보
포털에 커스텀 문서를 표시하려면 파일을 Git 저장소에 저장하고 포털의 설정 페이지에서 Git 저장소에 대한 URL을 구성해야 합니다. 다음 위치에 커스텀 문서 파일을 추가할 수 있습니다.
- API와 동일한 Google Cloud 프로젝트에 있는 Cloud Source Repositories의 비공개 저장소
- GitHub 또는 Bitbucket의 공개 저장소
Cloud Endpoints 포털에서 커스텀 문서를 찾고 표시하려면 저장소의 파일과 폴더가 특정 구조를 포함해야 합니다. 저장소 루트에 Cloud Endpoints 서비스 이름의 폴더가 필요합니다. 필요에 따라 추가 하위 폴더를 만들 수 있습니다. 왼쪽 탐색 메뉴에는 폴더 및 파일에 대한 링크가 포함되어 있습니다. 자세한 내용은 필수 디렉터리 구조를 참조하세요.
마크다운을 사용하여 시작 가이드 콘텐츠를 편집하고 추가 문서 페이지 콘텐츠를 작성할 수 있습니다. Endpoints 포털은 CommonMark 사양과 GitHub 맞춤형 마크다운 사양의 테이블 확장을 따릅니다.
또한 저장소에 이미지를 추가하고 마크다운 파일에서 이를 참조할 수 있습니다.
커스텀 문서 업데이트 시작하기
GitHub에 다음 파일이 포함된 endpoints-developer-portal-sample-content 저장소를 클론하면 시작하는 데 도움이 됩니다.
Getting Started.md: 포털에 표시되는 시작하기 페이지 예시의 콘텐츠가 포함된 마크다운 파일Example Page.md: 마크다운 사용을 시작하는 데 유용한 예시 파일navigation.yaml: 포털의 왼쪽 탐색 메뉴 페이지와 폴더 순서를 설명하는 파일add_example_page: 다음을 수행하는 스크립트- Google Cloud 프로젝트의 Cloud Source Repositories에 Git 저장소를 만듭니다.
default-content-repo폴더에 로컬 Git 저장소를 만듭니다.- Endpoints 서비스 이름과 동일한 이름의 폴더를 만들고
Guides라는 하위 폴더를 만듭니다. Example Page.md파일과Getting Started.md파일을Guides폴더에 추가합니다.Example Page를navigation.yaml파일에 추가합니다.- 새로 생성된 Cloud Source Repositories의 Git 저장소에 이러한 변경사항을 커밋 및 푸시합니다.
스크립트에는 다음과 같은 두 가지 버전이 있습니다.
- Linux 및 Mac 사용자용인
add_example_page.sh(Bash 셸) - Windows 사용자용인
add_example_page.ps1(PowerShell)
스크립트 실행은 선택사항이며 원한다면 Cloud Source Repositories, 공개 GitHub 또는 Bitbucket 저장소에 수동으로 저장소를 만드는 옵션도 있습니다. 커스텀 문서를 위한 필수 디렉토리 구조를 설정해야 합니다.
스크립트를 실행하기 전에 Cloud Source Repositories에 대한 가격 책정 및 할당량 문서를 검토하는 것이 좋습니다. 스크립트를 실행한 후 대신에 공개 GitHub 또는 Bitbucket 저장소를 사용하기로 결정한 경우에는 Cloud Source Repositories에서 저장소를 삭제할 수 있습니다.
커스텀 문서 시작용 파일 가져오기
이 섹션에서는 add_example_page 스크립트를 실행할 수 있도록 설정하는 방법을 설명합니다.
커스텀 문서 시작용 파일을 가져오려면 다음 단계를 따르세요.
Cloud Source Repositories API를 사용 설정합니다.
API 및 서비스에서 API 라이브러리 페이지로 이동합니다.
프로젝트 목록에서 API가 있는 프로젝트를 선택합니다.
Cloud Source Repositories API를 검색하고 카드를 클릭하여 정보 페이지를 표시합니다.
사용 설정을 클릭합니다.
gcloud CLI가 데이터와 서비스에 액세스할 수 있는 권한이 있는지 확인합니다.
gcloud auth login기본 프로젝트를 설정합니다. 다음 명령어에서
YOUR_PROJECT_ID를 Endpoints API를 만든 Google Cloud 프로젝트 ID로 바꿉니다.gcloud config set project YOUR_PROJECT_ID
샘플 콘텐츠, 구성, 스크립트를 다운로드합니다.
git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content스크립트가 포함된 디렉토리로 변경합니다.
cd endpoints-developer-portal-sample-content/scriptsEndpoints 서비스 이름을 표시합니다.
gcloud endpoints services listEndpoints 서비스 이름으로 스크립트를 실행합니다.
- Linux 및 Mac 사용자:
./add_example_page.sh SERVICE_NAME - Windows 사용자:
add_example_page.ps1 SERVICE_NAME
스크립트가 완료되면 URL이 다음 위치에 출력됩니다.
API의 포털 설정
Git URL. Cloud Source Repositories 페이지의 클론 URL 필드에 표시되는 URL과 동일한 URL입니다.
- Linux 및 Mac 사용자:
저장소를 포털에 동기화합니다.
- 첫 번째 URL을 강조 표시하고 복사한 후 브라우저의 주소 표시줄에 붙여 넣어 설정 페이지로 이동합니다.
- 로그인 메시지를 따라 API의 설정 페이지로 계속 진행합니다. 계정이 두 개 이상 있으면 API를 소유하는 Google Cloud 프로젝트에 있는 계정을 선택해야 합니다.
- Git 저장소의 클론 URL을 강조 표시하고 복사한 후 커스텀 콘텐츠 설정 필드에 붙여 넣습니다.
- 동기화를 클릭합니다.
- 저장을 클릭합니다.
- 제목 표시줄을 클릭하여 API 문서 방문 페이지로 돌아갑니다.
왼쪽 탐색 메뉴에서 페이지 예시를 클릭하여 콘텐츠를 표시합니다.
새로 생성된 저장소의 콘텐츠를 둘러봅니다. Google Cloud 콘솔에서 프로젝트의 소스 저장소 > 소스 코드 페이지로 이동합니다.
소스 코드 브라우저는 가장 최근 커밋 수준에서 저장소 콘텐츠의 디렉토리 보기를 표시합니다. 자세한 내용은 저장소 찾아보기를 참조하세요.
커스텀 문서 수정
이제 Cloud Source Repositories에 커스텀 문서가 있으므로 필요에 따라 콘텐츠를 수정하고 파일과 폴더를 추가 또는 삭제할 수 있습니다. Git를 처음 사용하는 경우, Git 문서에 포함된 참조 문서, 책과 동영상 링크를 참조하세요.
Getting Started 콘텐츠 수정
Getting Started 콘텐츠를 수정하려면 다음 안내를 따르세요.
로컬 Git 저장소의 루트에서 시작하여 Endpoints 서비스 이름과 동일한 이름의 폴더로 이동합니다. 예를 들면 다음과 같습니다.
cd example-api.example.comGetting Started.md가 포함된 폴더로 이동합니다.cd Guides텍스트 편집기에서
Getting Started.md를 엽니다.사용자가 API 사용을 시작하는 데 유용하도록 필요에 맞게 콘텐츠를 수정합니다.
파일을 저장합니다.
변경사항을 커밋합니다.
git commit -a -m "updated getting started"Cloud Source Repositories의 저장소에 변경사항을 푸시합니다.
git push업데이트된 콘텐츠를 포털에 동기화합니다.
- 포털로 이동합니다.
- 설정 을 클릭합니다.
- 설정 페이지에서 API 탭을 클릭하고 목록에서 API를 선택합니다.
- 동기화를 클릭합니다.
- 저장을 클릭합니다.
왼쪽 탐색 메뉴의 시작하기 링크를 클릭하면 Endpoints 포털에 업데이트된 콘텐츠가 표시됩니다.
Example Page 삭제
Example Page를 삭제하려면 다음 안내를 따르세요.
로컬 Git 저장소의 루트에서 시작하여 Endpoints 서비스 이름과 동일한 이름의 폴더로 이동합니다. 예를 들면 다음과 같습니다.
cd example-api.example.com텍스트 편집기에서
navigation.yaml파일을 엽니다.ordering섹션에서Example Page가 있는 줄을 삭제합니다.파일을 저장합니다.
Git에서
Example Page.md파일을 삭제합니다.git rm ‘Guides/Example Page.md'변경사항을 커밋합니다.
git commit -a -m "removed example page"Cloud Source Repositories의 저장소에 변경사항을 푸시합니다.
git push업데이트된 콘텐츠를 포털에 동기화합니다.
- 포털로 이동합니다.
- 설정 을 클릭합니다.
- 설정 페이지에서 API 탭을 클릭하고 목록에서 API를 선택합니다.
- 동기화를 클릭합니다.
- 저장을 클릭합니다.
Example Page가 더 이상 왼쪽 탐색 메뉴에 표시되지 않습니다.
Example Page 이름 바꾸기
Example Page 이름을 바꾸려면 다음 안내를 따르세요.
로컬 Git 저장소의 루트에서 시작하여 Endpoints 서비스 이름과 동일한 이름의 폴더로 이동합니다. 예를 들면 다음과 같습니다.
cd example-api.example.com텍스트 편집기에서
navigation.yaml파일을 엽니다.ordering섹션에서 예시 페이지를 가이드의 제목으로 변경합니다. 여기에 있는 이름은Guides디렉터리의 실제 파일 이름과 일치해야 합니다.파일을 저장합니다.
Git에서
Example Page.md파일 이름을 바꿉니다.git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'
이름을 바꾼 파일의 콘텐츠를 필요에 맞게 수정합니다.
변경사항을 커밋합니다.
git commit -a -m "removed example page"Cloud Source Repositories의 저장소에 변경사항을 푸시합니다.
git push업데이트된 콘텐츠를 포털에 동기화합니다.
- 포털로 이동합니다.
- 설정 을 클릭합니다.
- 설정 페이지에서 API 탭을 클릭하고 목록에서 API를 선택합니다.
- 동기화를 클릭합니다.
- 저장을 클릭합니다.
왼쪽 탐색 메뉴에 이름이 바뀐 페이지가 표시됩니다.
필수 디렉토리 구조
Endpoints 포털에서 커스텀 콘텐츠를 찾고 표시하려면 저장소의 파일과 폴더가 특정 구조로 되어 있어야 합니다.
저장소 루트에는 Endpoints 서비스 이름으로 된 폴더가 있어야 합니다. 이 구조는 각 API에 대한 별도의 루트 수준 폴더를 통해 여러 API에 저장소 한 개를 사용할 수 있는 옵션을 제공합니다.
서비스 폴더 내 하위 폴더를 통해 섹션 아래에서 관련 페이지를 그룹화하고 추가 하위 폴더를 포함할 수 있습니다. 폴더 제목과 파일 이름은 탐색에 사용됩니다. 예를 들어 Getting Started.md라는 파일은 왼쪽 탐색 메뉴에 Getting Started로 표시됩니다. Endpoints 서비스 이름의 폴더 내에는 navigation.yaml이라는 파일이 있어야 합니다. 이 파일은 포털의 왼쪽 탐색 메뉴에 콘텐츠를 표시할 방법을 지정합니다. 기본값은 다음과 비슷합니다.
ordering:
- Introduction
- Guides
- API Reference
- Resources
folders:
Guides:
ordering:
- Getting Started
- Example Page
첫 번째 ordering 목록은 해당 수준에서 항목이 표시되는 순서를 지정합니다. 예를 들어 기본 navigation.yaml 파일은 Introduction 페이지부터 표시하고 Guides 섹션 등을 이어서 표시하도록 지정합니다.
Introduction, API Reference, Resources는 특수 섹션이며 navigation.yaml에서 이러한 섹션을 삭제하지 않아야 합니다. 하지만 순서를 변경할 수 있습니다.
각 폴더와 페이지에는 navigation.yaml의 상위 folders 구성 내에 해당 구성이 있어야 합니다. 없을 경우에는 페이지 또는 폴더가 포털에 표시되지 않습니다. 예를 들어 기본 navigation.yaml 파일에서 folders 키는 같은 이름의 폴더가 있으므로 Guides라는 하위 키를 포함합니다.
이미지 추가
커스텀 콘텐츠 Git 저장소에 이미지를 추가하고 마크다운 파일에서 참조할 수 있습니다. 이미지와 이 이미지를 참조하는 마크다운 파일을 Endpoints 서비스 이름과 같은 이름의 디렉터리 아래에 두면 상대 URL(/로 시작)로 이미지를 참조할 수 있습니다.
예를 들어 다음과 같은 디렉터리 구조가 있다고 가정합니다.
~/example-api.example.com/
get-started.md
images/
example.jpg
다음 마크업으로 images/example.jpg 이미지를 get-started.md에 추가할 수 있습니다.
표준 마크다운 구문과 이미지의 전체 URL을 사용하여 다른 곳에 호스팅된 이미지를 추가할 수 있습니다.
포털은 다음과 같은 이미지 형식을 지원합니다.
- BMP
- GIF
- JPEG
- PNG
- TIFF
- WEBP
커스텀 콘텐츠 제한
포털에는 다음과 같은 커스텀 콘텐츠 제한 사항이 있습니다.
- API당 마크다운 페이지 최대 200개
- API당 이미지 최대 200개
- 이미지당 최대 크기 4MiB