除了 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
脚本。
如需获取自定义文档起始文件,请执行以下操作:
启用 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/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 页面的克隆网址字段中显示的网址相同。
- Linux 和 Mac 用户:
将代码库同步到您的门户:
- 突出显示并复制第一个网址,然后将其粘贴到浏览器的地址栏中,以转到设置页面。
- 按照登录提示继续访问 API 的设置页面。如果您有多个帐号,请务必选择 API 所属的 Google Cloud 项目中的帐号。
- 突出显示并复制 Git 代码库的克隆网址,然后将其粘贴到自定义内容设置字段中。
- 点击同步。
- 点击保存。
- 如需返回 API 文档着陆页,请点击标题栏。
在左侧导航栏中,点击示例页面以显示内容。
浏览新建代码库的内容。在 Google Cloud Console 中,转到项目的源代码库和源代码页面。
源代码浏览器会显示最近提交层级的代码库内容的目录视图。如需了解详情,请参阅浏览代码库。
修改自定义文档
现在,您已将自定义文档添加到 Cloud Source Repository 中,接下来就可以根据需要修改内容,并添加或删除文件及文件夹。如果您是刚接触 Git,请参阅 Git 文档,其中包含参考文档以及相关书籍和视频的链接。
修改 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
将更新后的内容同步到您的门户:
- 转到您的门户。
- 点击设置 。
- 在设置页面上,点击 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 代码库,并在 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。