更新 SmartDocs

在向您的 API 用户提供门户网址之前，请确保 SmartDocs API 参考文档正确无误，并且 API 的行为与文档中的说明一致。 当您查看生成的参考文档并进行测试时，可能会看到一些想要更改的内容。

本页介绍以下内容：

前提条件

本页面假定您已创建门户。

关于 SmartDocs API 参考文档

当您按照以下部分中的说明添加 API 管理时：

Endpoints Frameworks 为您的 API 创建一个 OpenAPI 文档。每次将 OpenAPI 文档部署到 Endpoints 服务后，SmartDocs 都会为您的门户网站生成 API 参考文档。SmartDocs 界面基于当前最先进的界面组件库 Angular Material。开发者可以查看您的 SmartDocs API 参考文档，并使用试用此 API 微件与您的 API 交互，而无需退出该 API 文档。

用于生成 SmartDocs 的字段简介

当您按照以下部分中的说明添加 API 管理时：

Endpoints Frameworks 将为您的 API 创建 JSON 格式的 OpenAPI 文档。在部署 OpenAPI 文档时（使用 gcloud endpoints services deploy），SmartDocs 会根据 Endpoints Frameworks 创建的 OpenAPI 文档生成更新的 API 参考文档。

Endpoints Frameworks 未在 OpenAPI 文档中加入它为您的 API 创建的说明。在向 API 用户提供门户网址之前，我们建议您向 OpenAPI 文档中的 API、方法和参数添加说明。

如果您不熟悉 OpenAPI，请从 Swagger 基本结构网站开始，该网站提供了 OpenAPI 示例文档，并简要说明了该文档的每个部分。如需了解详情，请参阅 OpenAPI 规范。

正如元数据部分所述，description 字段的值可以包含多行并且支持 GitHub Flauored Markdown。

为了帮助用户了解如何使用 API 中的方法，请在参数部分和请求正文中添加 description 字段。

您的 OpenAPI 文档包含如下内容：

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

上述字段的值按如下方式显示在门户中：

  • title：title 的值显示在门户首页（位于列出项目 API 的部分）、API 首页（末尾附有文档一词）和 API 标题栏中。

  • host：host 的值（同时也是 Endpoints 服务的名称）显示在门户首页（位于列出项目 API 的部分）和设置页面（位于 API 标签页显示的下拉列表中）上。

  • version：用于 API 门户的网址的主要版本号。

您可能希望更改 title 字段中的值，并为 API 添加 description 字段。例如：

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

重新生成 SmartDocs

要重新生成参考文档，请执行以下操作：

  1. 对 Endpoints Frameworks 生成的 openapi.json 文件进行更改。

  2. 重新部署 openapi.json：

    gcloud endpoints services deploy openapi.json

  3. 刷新门户页面。

  4. 如果您随后需要重新生成 openapi.json 文件，请将修改后的 openapi.json 文件保存到无法覆盖的位置。如果您更改了 API 并重新生成了 openapi.json 文件，则需将重新生成的 openapi.json 中的更改与先前所做的更改进行合并。

请参阅 gcloud endpoints services deploy，详细了解该命令。