Antes de informar o URL do portal aos usuários da API, verifique se a documentação de referência da API SmartDocs está correta e se o funcionamento da API está de acordo com a documentação. Ao revisar a documentação de referência e o teste gerados, talvez você veja algo que queira alterar.
Nesta página, você verá:- a documentação de referência da API SmartDocs;
- como os campos e comentários dos arquivos de configuração
.proto
e do serviço são usados para gerar SmartDocs; - como regenerar SmartDocs.
- Como entender os papéis
- Como conceder, alterar e revogar acesso a recursos
- Como criar e gerenciar papéis personalizados
Pré-requisitos
Nesta página, presume-se que você já tenha criado seu portal.
Sobre a documentação de referência da API SmartDocs
Sempre que você implanta uma configuração de serviço no seu serviço Cloud Endpoints, a documentação de referência da API é gerada para seu portal pelo SmartDocs. A IU do SmartDocs é baseada em Angular Material, uma biblioteca de componentes de IU de última geração. Os desenvolvedores podem ler a documentação de referência da API SmartDocs e usar o widget Testar esta API para interagir com a API sem sair da documentação.Sobre os campos usados para gerar SmartDocs
Seu arquivo de configuração de serviço, conhecido como api_config.yaml
, contém algo como o seguinte:
title: Bookstore gRPC API apis: - name: endpoints.examples.bookstore.Bookstore
title
: o valor do título é exibido na página inicial do portal na seção que lista as APIs do projeto, na página inicial da API com a palavra documentação anexada e na barra de título da API.name
: o valor dename
, que também é o nome do serviço do Endpoints, é exibido na seção que lista as APIs do projeto na página inicial e na página Configurações na lista suspensa exibida na guia APIs.
O Portal do Cloud Endpoints gera a documentação de referência para cada método RPC e recurso no arquivo .proto
. Os comentários associados a cada método e recurso estão incluídos na documentação exibida no portal. O trecho a seguir é do arquivo .proto
usado para gerar a documentação de referência do exemplo da API gRPC do Bookstore na Demonstração do portal do Endpoints:
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) {} }
O anúncio bookstore.proto
completo usado na demonstração do portal do Endpoints está na amostra bookstore-grpc
do Endpoints.
Como regenerar SmartDocs
Para gerar a documentação de referência:
Faça alterações na configuração do serviço e/ou nos seus arquivos
.proto
.Se você alterou seu arquivo
.proto
, compile seus buffers de protocolo.Reimplante o arquivo
.pb
e o arquivo de configuração de serviço, por exemplo:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Atualize a página do portal.
Veja gcloud endpoints services deploy
para saber mais sobre o comando.