添加自定义文档

除了 SmartDocs API 参考文档之外，您还可以向自己的门户添加您的 API 用户可能需要的自定义文档。即使您不需要向用户提供其他文档页面，也需要更新门户中显示的示例入门指南，说明如何开始使用您的 API。

本页面介绍如何更改示例入门指南，以及如何为您的门户创建和显示其他文档页面。对于每项任务，本文都指出了完成该任务所需最低权限对应的 Identity and Access Management 角色。如需详细了解 IAM 权限，请参阅以下内容：

前提条件

本页面假定您已经完成以下操作：

关于自定义文档

为了在您的门户中显示自定义文档，您必须将文件存储在一个 Git 代码库中，并在门户的设置页面上配置该 Git 代码库的网址。您可以将您的自定义文档文件添加到以下位置：

Cloud Source Repositories 中的私有代码库，该代码库应与您的 API 位于同一 Google Cloud 项目。
GitHub 或 Bitbucket 中的公共代码库。

为使 Cloud Endpoints 门户能够找到并显示您的自定义文档，您的代码库中的文件和文件夹必须采用特定结构。在此代码库的根目录下，必须存在一个与 Cloud Endpoints 服务名称相同的文件夹。您可以根据需要创建其他子文件夹。左侧导航栏包含指向您的文件夹和文件的链接。如需了解详情，请参阅所需目录结构

您可以使用 Markdown 修改入门指南中的内容，以及编写其他文档页面的内容。Endpoints 门户遵循 CommonMark 规范，以及 GitHub Flavored Markdown 规范中的附加表格信息。

您还可以向代码库中添加图片，并在 Markdown 文件中引用这些图片。

开始更新自定义文档

为了帮助您顺利上手，我们建议您克隆 GitHub 上的 endpoints-developer-portal-sample-content 代码库，其中包含以下文件：

Getting Started.md：此 Markdown 文件包含您的门户中显示的示例使用入门页面的内容。
Example Page.md：此示例文件旨在帮助您开始使用 Markdown。
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 shell)。
- 适用于 Windows 用户的 add_example_page.ps1 （PowerShell）。
运行脚本的操作是可选的。您可以在 Cloud Source Repositories 中手动创建一个代码库，也可以改为在公共 GitHub 或 Bitbucket 代码库中创建，这取决于您自己的喜好。您需要为自定义文档设置所需的目录结构。

在运行脚本之前，建议您查看 Cloud Source Repositories 价格和配额文档。如果您在运行该脚本后又决定改用公共 GitHub 或 Bitbucket 代码库，可以从 Cloud Source Repositories 中删除代码库。

获取自定义文档起始文件

本部分介绍如何完成设置以便于运行 add_example_page 脚本。

执行此任务所需的权限

如需执行此任务，您必须具有项目的 Project Editor 角色。此角色具备以下权限：

启用 Cloud Source Repositories API。
在 Cloud Source Repositories 中创建代码库。
将代码库内容同步到 API 的门户。

如需获取自定义文档起始文件，请执行以下操作：

启用 Cloud Source Repositories API：
1. 在“API 和服务”中，转到 API 库页面。
  转到“API 库”
2. 从项目列表中选择 API 所属的项目。
3. 搜索 Cloud Source Repositories API，然后点击其对应卡片以显示其信息页面。
4. 点击启用。
确保 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/scripts

显示您的 Endpoints 服务名称：
```
gcloud endpoints services list
```
运行与您的 Endpoints 服务同名的脚本：
- Linux 和 Mac 用户：./add_example_page.sh SERVICE_NAME
- Windows 用户：add_example_page.ps1 SERVICE_NAME
该脚本运行完成后，会将网址输出到以下位置：
- 您的 API 的门户设置。
- 您的 Git 网址。此网址与 Cloud Source Repositories 页面的克隆网址字段中显示的网址相同。
将代码库同步到您的门户：
1. 突出显示并复制第一个网址，然后将其粘贴到浏览器的地址栏中，以转到设置页面。
2. 按照登录提示继续访问 API 的设置页面。如果您有多个帐号，请务必选择 API 所属的 Google Cloud 项目中的帐号。
3. 突出显示并复制 Git 代码库的克隆网址，然后将其粘贴到自定义内容设置字段中。
4. 点击同步。
5. 点击保存。
6. 如需返回 API 文档着陆页，请点击标题栏。
在左侧导航栏中，点击示例页面以显示内容。
浏览新建代码库的内容。在 Google Cloud Console 中，转到项目的源代码库和源代码页面。
转到“源代码浏览器”

源代码浏览器会显示最近提交层级的代码库内容的目录视图。如需了解详情，请参阅浏览代码库。

修改自定义文档

现在，您已将自定义文档添加到 Cloud Source Repository 中，接下来就可以根据需要修改内容，并添加或删除文件及文件夹。如果您是刚接触 Git，请参阅 Git 文档，其中包含参考文档以及相关书籍和视频的链接。

执行此任务所需的权限

如需执行此任务，您必须具有项目的 Project Editor 角色。此角色具备以下权限：

修改 Cloud Source Repositories 中的内容
将代码库内容同步到 API 的门户。

修改 `Getting Started` 内容

如需修改 Getting Started 内容，请执行以下操作：

从本地 Git 代码库的根目录，转到与 Endpoints 服务同名的文件夹。例如：
```
cd example-api.example.com
```
转到包含 Getting Started.md 的文件夹：
```
cd Guides
```
通过文本编辑器打开 Getting Started.md。
根据需要修改内容，以帮助用户开始使用您的 API。
保存文件。

提交所做的更改：

git commit -a -m "updated getting started"

将更改推送到 Cloud Source Repositories 中的相应代码库：
```
git push
```
将更新后的内容同步到您的门户：
1. 转到您的门户。
2. 点击设置。
3. 在设置页面上，点击 API 标签页，然后从列表中选择您的 API。
4. 点击同步。
5. 点击保存。
当您点击左侧导航栏中的使用入门链接时，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
```
将更新后的内容同步到您的门户：
1. 转到您的门户。
2. 点击设置。
3. 在设置页面上，点击 API 标签页，然后从列表中选择您的 API。
4. 点击同步。
5. 点击保存。

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
```
将更新后的内容同步到您的门户：
1. 转到您的门户。
2. 点击设置。
3. 在设置页面上，点击 API 标签页，然后从列表中选择您的 API。
4. 点击同步。
5. 点击保存。

已更改名称的页面将显示在左侧导航栏中。

所需目录结构

为使 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 代码库，并在 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。

添加自定义文档

前提条件

关于自定义文档

开始更新自定义文档

获取自定义文档起始文件

执行此任务所需的权限

修改自定义文档

执行此任务所需的权限

修改 Getting Started 内容

移除 Example Page

重命名 Example Page

所需目录结构

添加图片

自定义内容限制

后续步骤

修改 `Getting Started` 内容

移除 `Example Page`

重命名 `Example Page`