Aggiornamento di SmartDocs

OpenAPI | gRPC

Prima di fornire l'URL del portale agli utenti della tua API, assicurati che la documentazione di riferimento dell'API SmartDocs sia corretta e che l'API si comporti come descritto. Se testi la documentazione di riferimento generata e la verifica, potresti notare alcune modifiche.

In questa pagina vengono descritti:

Documentazione di riferimento dell'API SmartDocs
In che modo SmartDocs utilizza i campi e i commenti nei file .proto e nei file di configurazione del servizio per generare SmartDocs
Come rigenerare SmartDocs

Per ogni attività viene fornito il ruolo (o i ruoli) minimo richiesto per completare l'attività. Per ulteriori informazioni sulle autorizzazioni IAM, consulta quanto segue:

Prerequisiti

Questa pagina presuppone che tu abbia già creato il tuo portale.

Informazioni sulla documentazione di riferimento dell'API SmartDocs

Ogni volta che esegui il deployment di una configurazione del servizio nel servizio Endpoints, SmartDocs genera la documentazione di riferimento dell'API per il portale. L'interfaccia utente di SmartDocs si basa su Angular Material, una libreria all'avanguardia per i componenti dell'interfaccia utente. Gli sviluppatori possono esaminare la documentazione di riferimento dell'API SmartDocs e utilizzare il widget Prova questa API per interagire con l'API senza uscire dalla documentazione dell'API.

Informazioni sui campi utilizzati per generare SmartDocs

Il file di configurazione del servizio (noto come api_config.yaml) contiene elementi simili ai seguenti:

title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.Bookstore

title: il valore del titolo viene visualizzato nella home page del portale nella sezione che elenca le API nel progetto, nella home page dell'API (con la parola documentazione aggiunta) e nella barra del titolo dell'API.
name: il valore per name (che è anche il nome del tuo servizio Endpoint) viene visualizzato nella home page del portale nella sezione che elenca le API nel progetto e nella pagina Impostazioni nell'elenco a discesa visualizzato nella scheda API.

Il portale Endpoints genera la documentazione di riferimento per ogni risorsa e metodo RPC nel file .proto. I commenti associati a ogni metodo e risorsa sono inclusi nella documentazione visualizzata nel tuo portale. Il seguente estratto del file .proto viene usato per generare la documentazione di riferimento per l'esempio dell'API Bookstore gRPC nella demo del Portale endpoint:

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) {}
}

Il file bookstore.proto completo utilizzato nella demo del portale degli endpoint è incluso nell'esempio di endpoint bookstore-grpc.

Rigenerazione di Documenti smart

Autorizzazioni richieste per questa attività

Per rigenerare SmartDocs, esegui il deployment della configurazione degli endpoint aggiornata. Il ruolo Editor di configurazione del servizio concesso per il servizio dispone delle autorizzazioni minime richieste per eseguire nuovamente il deployment della configurazione degli endpoint. Per informazioni su come assegnare questo ruolo, consulta l'articolo Concessione e revoca dell'accesso all'API.

Per rigenerare la documentazione di riferimento:

Apporta le modifiche alla configurazione del servizio e/o ai tuoi file .proto.
Se hai modificato il file .proto, compila i buffer di protocollo.
Esegui nuovamente il deployment del tuo file .pb e del tuo file di configurazione del servizio, ad esempio:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
Aggiorna la pagina del portale.

Scopri di più sul comando gcloud endpoints services deploy.