Before you provide your portal URL to the users of your API, make sure that the SmartDocs API reference documentation is correct, and that the API is behaving as documented. As you review the generated reference documentation and test, you might see something that you want to change.
This page describes:- The SmartDocs API reference documentation
- How SmartDocs uses the fields and comments in your
.proto
and service configuration files to generate SmartDocs - How to regenerate SmartDocs
- Understanding roles
- Granting, changing, and revoking access to resources
- Creating and managing custom roles
Prerequisites
This page assumes that you have already created your portal.
About the SmartDocs API reference documentation
Every time you deploy a service configuration to your Endpoints service, SmartDocs generates API reference documentation for your portal. The SmartDocs UI is based on Angular Material, a state-of-the-art UI components library. Developers can review your SmartDocs API reference documentation and use the Try this API widget to interact with your API without leaving the API documentation.About the fields used to generate SmartDocs
Your service configuration file (referred to as api_config.yaml
)
contains something like the following:
title: Bookstore gRPC API apis: - name: endpoints.examples.bookstore.Bookstore
title
: The value for the title is displayed on your portal homepage in the section that lists the APIs in the project, the API homepage (with the word documentation appended to it), and in the API title bar.name
: The value forname
(which is also the name of your Endpoints service) is displayed on your portal homepage in the section that lists the APIs in the project, and on the Settings page in the drop-down list displayed on the APIs tab.
The Endpoints Portal generates reference documentation for each
RPC method and resource in your .proto
file. The comments associated with each
method and resource are included in the documentation that is displayed in your
portal. The following excerpt is from the .proto
file used to generate the
reference documentation for the Bookstore gRPC API example in the
Endpoints Portal demo:
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) {} }
The complete bookstore.proto
file used in the Endpoints Portal
demo is in the
bookstore-grpc
Endpoints sample.
Regenerating SmartDocs
To regenerate the reference documentation:
Make the changes to your service configuration and/or your
.proto
files.If you changed your
.proto
file, compile your protocol buffers.Redeploy your
.pb
file and your service configuration file, for example:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Refresh your portal page.
See
gcloud endpoints services deploy
to learn more about the command.