新增自訂說明文件

除了 SmartDocs API 參考說明文件外,您也可以在入口網站中加入您的 API 使用者可能需要的自訂說明文件。即使您不需要提供使用者額外的說明文件頁面,您還是必須更新入口網站上顯示的「入門指南」範例,以便說明如何開始使用您的 API。

本頁說明如何更改「入門指南」範例,以及如何在入口網站建立及顯示額外的說明文件頁面。針對每項工作,系統會提供完成該工作所需的 Cloud Identity & Access Management 最低權限角色。如要進一步瞭解 Cloud IAM 權限,請參閱以下內容:

事前準備

本頁面假設您已經:

關於自訂說明文件

如要在入口網站顯示自訂說明文件,您必須將檔案儲存在 Git 存放區,並在入口網站的「Settings」(設定) 頁面上設定 Git 存放區的網址。您可以將自訂說明文件的檔案新增到以下位置:

  • Cloud Source Repositories 中的私人存放區,而該存放區與您的 API 都位於同一個 Google Cloud Platform (GCP) 專案中。
  • GitHub 或 Bitbucket 中的公開存放區。

存放區內的檔案和資料夾必須採用特定結構,以利 Cloud Endpoints 入口網站找到並顯示您的自訂說明文件。在存放區的根目錄中,必須要有採用您 Cloud Endpoints 服務名稱的資料夾。您可以視需要建立額外的子資料夾。左側導覽列包含的連結可以連至您的資料夾和檔案。詳情請參閱必要的目錄結構一節

您可以使用 Markdown 編輯「入門指南」的內容,以及撰寫額外說明文件頁面的內容。Endpoints 入口網站會依循 CommonMark 規格,以及 GitHub Flavored Markdown 規格中的表格額外資訊說明。

您也可以新增圖片到存放區,再從 Markdown 檔案參照這些圖片。

開始更新自訂說明文件

為協助您快速入門,建議您複製 GitHub 上的 endpoints-developer-portal-sample-content 存放區,其中包含以下檔案:

  • Getting Started.md:Markdown 檔案,其中包含入口網站顯示的「Getting Started」(入門指南) 頁面範例的內容。
  • Example Page.md:協助您開始使用 Markdown 的範例檔案。
  • navigation.yam:說明入口網站左側導覽列中頁面和資料夾順序的檔案。
  • add_example_page:可進行下列操作的指令碼:

    • 在您 GCP 專案內的 Cloud Source Repositories 中建立 Git 存放區。
    • default-content-repo 資料夾中建立本機 Git 存放區。
    • 建立與您的 Endpoints 服務名稱同名的資料夾,並建立名為 Guides 的子資料夾。
    • Guides 資料夾中新增名為 Example Page.mdGetting Started.md 的檔案。
    • 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 指令碼。

如何取得自訂說明文件入門檔案:

  1. 啟用 Cloud Source Repositories API:

    1. 在「APIs & services」(API 和服務) 中,前往「API Library」(API 程式庫) 頁面。

      前往「API Library」(API 程式庫) 頁面

    2. 在專案清單中選取 API 所屬的專案。

    3. 搜尋 Cloud Source Repositories API,按一下該 API 的卡片,顯示其資訊頁面。

    4. 按一下 [Enable] (啟用)

  2. 確認 Cloud SDK 已取得授權,能夠存取您的資料和服務:

    gcloud auth login
    
  3. 設定預設專案。在下列指令中,請將 [YOUR-PROJECT-ID] 替換成您在其中建立 Endpoints API 的 GCP 專案 ID:

    gcloud config set project [YOUR_PROJECT_ID]
    
  4. 下載範例內容、設定以及指令碼:

    git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content
    
  5. 變更為包含指令碼的目錄:

    cd endpoints-developer-portal-sample-content/scripts
    
  6. 顯示您的 Endpoints 服務名稱:

    gcloud endpoints services list
    
  7. 使用您的 Endpoints 服務名稱執行該指令碼:

    • Linux 和 Mac 使用者:./add_example_page.sh [SERVICE_NAME]
    • Windows 使用者:add_example_page.ps1 [SERVICE_NAME]

    指令碼執行結束時,會顯示網址至下列位置:

    • 您的 API 入口網站設定。

    • 您的 Git 網址。這個網址與 Cloud Source Repositories 頁面中 [Clone URL] (複本網址) 欄位所顯示的網址相同。

  8. 將存放區與入口網站同步:

    1. 反白選取並複製第一個網址,再將網址貼到瀏覽器的網址列,以便進入「Settings」(設定) 頁面。
    2. 按照登入提示繼續前往 API 的「Settings」(設定) 頁面。如果您有多個帳戶,請務必選擇在擁有 API 的 GCP 專案中的帳戶。
    3. 反白選取並複製 Git 存放區的複本網址,然後將該網址貼到 [Custom Content Settings] (自訂內容設定) 欄位中。
    4. 按一下 [Sync] (同步處理)
    5. 按一下 [Save] (儲存)
    6. 按一下標題列即可返回 API 說明文件的到達網頁。

    在左側導覽列中,按一下 [Example Page] (範例頁面) 以顯示內容。

  9. 瀏覽新建存放區的內容。請在 GCP 主控台中,前往您專案的「Source Repositories」>「Source code」(原始碼) 頁面。

    前往原始碼瀏覽器

    原始碼瀏覽器會依最近修訂層級,顯示存放區內容的目錄視圖。詳情請參閱瀏覽存放區

修改自訂說明文件

現在 Cloud Source Repositories 中已存有自訂說明文件,您可以視需要修改內容、新增或刪除檔案和資料夾。如果您是 Git 的新手,請參閱包含參考說明文件及書籍和影片連結的 Git 說明文件

修改入門指南的內容

如何修改入門指南的內容:

  1. 從本機 Git 存放區的根目錄開始,前往名稱與您 Endpoints 服務相同的資料夾。例如:

    cd example-api.example.com
    
  2. 進入包含 Getting Started.md 的資料夾:

    cd Guides
    
  3. 在文字編輯器中開啟「Getting Started.md」

  4. 根據需求修改內容,協助使用者開始使用您的 API。

  5. 儲存檔案。

  6. 修訂變更:

    git commit -a -m "updated getting started"
    
  7. 將變更推送至 Cloud Source Repositories 中的存放區:

    git push
    
  8. 將更新後的內容同步到您的入口網站:

    1. 瀏覽至您的入口網站。
    2. 按一下 [settings] (設定)
    3. 在「Settings」(設定) 頁面中按一下 [API] 分頁標籤,然後從下拉式清單中選取您的 API。
    4. 按一下 [Sync] (同步處理)
    5. 按一下 [Save] (儲存)

    按一下左側導覽列的 [Getting Started] (入門指南) 連結時,Endpoints 入口網站便會顯示更新後的內容。

移除範例頁面

如何移除範例頁面:

  1. 從本機 Git 存放區的根目錄開始,前往名稱與您 Endpoints 服務相同的資料夾。例如:

    cd example-api.example.com
    
  2. 在文字編輯器中開啟 navigation.yaml

  3. ordering 區段中刪除註明「範例頁面」的文字行。

  4. 儲存檔案。

  5. 從 Git 中移除「Example Page.md」檔案:

    git rm ‘Guides/Example Page.md'
    
  6. 修訂變更:

    git commit -a -m "removed example page"
    
  7. 將變更推送至 Cloud Source Repositories 中的存放區:

    git push
    
  8. 將更新後的內容同步到您的入口網站:

    1. 瀏覽至您的入口網站。
    2. 按一下 [settings] (設定)
    3. 在「Settings」(設定) 頁面中按一下 [API] 分頁標籤,然後從下拉式清單中選取您的 API。
    4. 按一下 [Sync] (同步處理)
    5. 按一下 [Save] (儲存)

現在左側導覽列已經沒有範例頁面了。

為範例頁面重新命名

如何為範例頁面重新命名:

  1. 從本機 Git 存放區的根目錄開始,前往名稱與您 Endpoints 服務相同的資料夾。例如:

    cd example-api.example.com
    
  2. 在文字編輯器中開啟 navigation.yaml

  3. ordering 部分中,將「Example Page」(範例頁面) 更改成您入門指南的標題。這個名稱必須與 Guides 目錄中的實際檔案名稱相符。

  4. 儲存檔案。

  5. 將 Git 中的 Example Page.md 檔案重新命名。

    git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'
  6. 視需要修改重新命名檔案的內容。

  7. 修訂變更:

    git commit -a -m "removed example page"
    
  8. 將變更推送至 Cloud Source Repositories 中的存放區:

    git push
    
  9. 將更新後的內容同步到您的入口網站:

    1. 瀏覽至您的入口網站。
    2. 按一下 [settings] (設定)
    3. 在「Settings」(設定) 頁面中按一下 [API] 分頁標籤,然後從下拉式清單中選取您的 API。
    4. 按一下 [Sync] (同步處理)
    5. 按一下 [Save] (儲存)

重新命名的頁面會顯示在左側導覽列中。

必要的目錄結構

存放區內的檔案和資料夾必須採用特定結構,以利 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 部分,以此類推。

IntroductionAPI ReferenceResources 都是特殊部分,請勿將它們從 navigation.yaml 中移除,但您可以變更它們的順序。

每個資料夾及頁面在自己位於 folders 檔案的父項 navigation.yaml 設定中,都應該要有對應的設定。如果您省略這些設定,該頁面或資料夾就不會出現在入口網站中。例如在預設的 navigation.yaml 中,folders 金鑰包含名為 Guides 的子金鑰 (因為有一個名稱相同的資料夾)。

新增圖片

您可以將圖片新增到自訂內容 Git 存放區中,並在 Markdown 檔案中參照這些圖片。如果您將圖片和任何參照圖片的 Markdown 檔案放在與 Endpoints 服務名稱相同的目錄,您就可以使用相對網址 (以 / 開頭) 來參照圖片。

例如,假設您的目錄結構如下所示:

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

您可以使用以下標記將 images/example.jpg 圖片新增至 get-started.md

    ![alt-text](/images/example.jpg "Optional title")

您可以使用標準 Markdown 語法和圖片的完整網址,新增託管在他處的圖片:

    ![alt-text](https://example.com/image.png "Optional title")

入口網站支援以下圖片類型:

  • BMP
  • GIF
  • JPEG
  • PNG
  • TIFF
  • WEBP

自訂內容限制

入口網站的自訂內容有以下限制:

  • 每個 API 最多 200 個 Markdown 頁面。
  • 每個 API 最多 200 張圖片。
  • 每張圖片的大小不可超過 4 MiB。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁