Como atualizar SmartDocs

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 gerar o SmartDocs novamente.
Para a conclusão de cada tarefa, é fornecido o papel mínimo exigido 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 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 seu serviço Endpoints, é exibido na seção que lista as APIs do projeto na página inicial do portal 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 arquivo bookstore.proto completo usado na demonstração do portal do Endpoints está na amostra bookstore-grpc do Endpoints.

Como gerar o SmartDocs novamente

Para gerar a documentação de referência, siga estas etapas:

  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 o arquivo .pb e o 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.

Veja gcloud endpoints services deploy para saber mais sobre o comando.