在向您的 API 用户提供门户网址之前,请确保 SmartDocs API 参考文档正确无误,并且 API 的行为与文档中的说明一致。 当您查看生成的参考文档并进行测试时,可能会看到一些想要更改的内容。
本页面介绍以下内容:- SmartDocs API 参考文档
- SmartDocs 如何使用
.proto
和服务配置文件中的字段和注释来生成 SmartDocs - 如何重新生成 SmartDocs
前提条件
本页面假定您已创建门户。
关于 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
要重新生成参考文档,请执行以下操作:
对服务配置和/或
.proto
文件进行更改。如果您更改了
.proto
文件,请编译协议缓冲区。重新部署您的
.pb
文件和服务配置文件,例如:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
刷新门户页面。
请参阅 gcloud endpoints services deploy
,详细了解该命令。