Como atualizar SmartDocs

Antes de informar o URL do portal aos usuários da sua API, convém verificar se a documentação de referência da API SmartDocs está correta e se o comportamento da API está de acordo com a documentação. Ao revisar a documentação de referência gerada e o teste, é provável que você veja algo que queira alterar.

Nesta página, descrevemos:

  • 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 gerar novamente os SmartDocs.
Para a conclusão de cada tarefa, são fornecidos os papéis mínimos exigidos do Cloud Identity and Access Management. Para mais informações sobre as permissões do Cloud IAM, consulte:

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 revisar 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, referido como api_config.yaml abaixo, conterá algo semelhante ao seguinte texto:

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 seu serviço Endpoints, é exibido na página inicial do portal, na seção que lista as APIs do projeto 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 acima de cada método e recurso são incluídos na documentação que é exibida no seu portal. O trecho a seguir é do arquivo .proto usado para gerar a documentação de referência do exemplo da API gRPC 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 arquivo bookstore.proto completo usado na Demonstração do portal do Endpoints está na amostra bookstore-grpc do Endpoints.

Como gerar SmartDocs novamente

Para gerar novamente a documentação de referência:

  1. Faça alterações na configuração do serviço e/ou nos seus arquivos .proto.

  2. Se tiver alterado o arquivo .proto, faça uma compilação dos buffers do protocolo.

  3. Implante novamente seu arquivo .pb e seu arquivo de configuração de serviço, por exemplo:

    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    
  4. Atualize a página do portal.

Para saber mais sobre o comando gcloud endpoints services deploy, consulte a referência do gcloud.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.