更新 SmartDocs

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

本页面介绍以下内容：

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

前提条件

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

关于 SmartDocs API 参考文档

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

用于生成 SmartDocs 的字段简介

您的服务配置文件（称为 api_config.yaml）包含如下内容：

title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.Bookstore

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

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

Endpoints 门户为您的 .proto 文件中的每个 RPC 方法和资源生成参考文档。与每种方法和资源关联的注释都包含在门户中显示的文档中。以下摘录自 .proto 文件，用于为 Endpoints 门户演示中的 Bookstore gRPC API 示例生成参考文档：

service Bookstore {
  // Returns a list of all shelves in the bookstore.
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {}
  // Creates a new shelf in the bookstore.
  rpc CreateShelf(CreateShelfRequest) returns (Shelf) {}
  // Returns a specific bookstore shelf.
  rpc GetShelf(GetShelfRequest) returns (Shelf) {}
  // Deletes a shelf, including all books that are stored on the shelf.
  rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {}
  // Returns a list of books on a shelf.
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {}
  // Creates a new book.
  rpc CreateBook(CreateBookRequest) returns (Book) {}
  // Returns a specific book.
  rpc GetBook(GetBookRequest) returns (Book) {}
  // Deletes a book from a shelf.
  rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {}
}

Endpoints 门户演示中使用的完整 bookstore.proto 文件位于 bookstore-grpc Endpoints 示例中。

重新生成 SmartDocs

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

  1. 对服务配置和/或 .proto 文件进行更改。

  2. 如果您更改了 .proto 文件，请编译协议缓冲区。

  3. 重新部署您的 .pb 文件和服务配置文件，例如：

    gcloud endpoints services deploy api_descriptor.pb api_config.yaml

  4. 刷新门户页面。

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