Como atualizar SmartDocs

OpenAPI | gRPC

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.

Para a conclusão de cada tarefa, são fornecidos os papéis mínimos exigidos do Identity and Access Management. Para mais informações sobre as permissões do IAM, consulte o seguinte:

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 de name, 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

Permissões necessárias para a tarefa

Para gerar o SmartDocs novamente, implante a configuração atualizada do Endpoints. O papel Editor de configuração do serviço concedido no serviço fornece as permissões mínimas necessárias para reimplantar a configuração do Endpoints. Consulte Como conceder e revogar o acesso à API para mais informações sobre como atribuir esse papel.

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.