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 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

Para gerar 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 você alterou seu arquivo .proto, compile seus buffers de protocolo.

  3. 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
    
  4. Atualize a página do portal.

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