更新 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 标题栏中。

  • namename 的值(同时也是 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,详细了解该命令。