更新 SmartDocs

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

本页介绍以下内容：

  • SmartDocs API 参考文档
  • SmartDocs 如何使用 OpenAPI 文档中的字段生成 SmartDocs
  • 如何重新生成 SmartDocs
对于每项任务，本文都指出了完成该任务所需最低权限对应的 Identity and Access Management 角色。如需详细了解 IAM 权限，请参阅以下内容：

前提条件

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

关于 SmartDocs API 参考文档

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

用于生成 SmartDocs 的字段简介

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

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

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

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

  • description：description 的值以小字体显示在 API 首页的标题下方。

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

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

Endpoints 门户会为 OpenAPI 文档的 paths 部分中列出的每个端点生成参考文档。以下摘录来自 OpenAPI 文档，该文档用于在 Endpoints 门户演示中的“Endpoints 示例 API”中生成 echo 端点的参考文档：

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []

echo 端点的参数在以下部分定义： 

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"

Endpoints 门户演示中使用的完整 openapi.yaml 文件位于 getting-started Endpoints 示例中。

最佳做法是始终在属性定义以及 OpenAPI 文档的所有其他部分中包含 description 字段。description 字段可以包含多个行，并且支持 GitHub Flauored Markdown。例如，以下内容会在门户的 API 首页上创建一个项目符号列表：

swagger: "2.0"
info:
  description: "A simple API to help you learn about Cloud Endpoints.

  * item 1

  * item 2"
title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

重新生成 SmartDocs

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

  1. 对 OpenAPI 文档进行更改。

  2. 重新部署 OpenAPI 文档（在以下命令中称为 openapi.yaml）：

    gcloud endpoints services deploy openapi.yaml

  3. 刷新门户页面。

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