Updating SmartDocs

OpenAPI | gRPC

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

For each task, the minimum required Cloud Identity and Access Management role (or roles) required to complete the task is provided. For more information about Cloud IAM permissions, see the following:

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 for name (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

Permissions required for this task

To regenerate SmartDocs, you deploy your updated Endpoints configuration. The Service Config Editor role granted on the service has the minimum required permissions to redeploy the Endpoints configuration. See Granting and revoking access to the API for information on how to assign this role.

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.