SmartDocs aktualisieren

OpenAPI | gRPC

Bevor Sie den Nutzern Ihrer API die URL des Portals zur Verfügung stellen, sollten Sie überprüfen, ob die Referenzdokumentation zur SmartDocs API korrekt ist und sich die API so verhält, wie in der Dokumentation beschrieben. Beim Durchsehen und Testen der generierten Referenzdokumentation werden Sie eventuell etwas sehen, das Sie ändern möchten.

Auf dieser Seite wird Folgendes beschrieben:

Die Referenzdokumentation der SmartDocs API
Wie SmartDocs die Felder und Kommentare in Ihren .proto.proto- und Dienstkonfigurationsdateien verwendet, um SmartDocs zu generieren
Wie SmartDocs regeneriert wird

Zu jeder Aufgabe werden die Rollen für Identity and Access Management (IAM) angegeben, die mindestens für die Durchführung der Aufgabe erforderlich sind. Weitere Informationen zu IAM-Berechtigungen finden Sie hier:

Voraussetzungen

Auf dieser Seite wird davon ausgegangen, dass Sie bereits ein Portal erstellt haben.

Informationen zur Referenzdokumentation der SmartDocs API

Bei jeder Bereitstellung einer Dienstkonfiguration für Ihren Cloud Endpoints-Dienst generiert SmartDocs eine API-Referenzdokumentation für Ihr Portal. Die UI von SmartDocs basiert auf Angular Material, einer hochmodernen Bibliothek für UI-Komponenten. Entwickler können die Referenzdokumentation der SmartDocs API aufrufen und über das Widget API testen mit Ihrer API interagieren, ohne die API-Dokumentation zu verlassen.

Felder für die SmartDocs-Generierung

Ihre Dienstkonfigurationsdatei (api_config.yaml genannt) enthält Folgendes:

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

title: Der Wert für den Titel wird auf der Startseite des Portals in dem Abschnitt angezeigt, in dem die APIs des Projekts aufgeführt sind, auf der API-Startseite (mit dem angehängten Wort documentation) und in der API-Titelleiste.
name: Der Wert für name (entspricht dem Namen Ihres Endpoints-Dienstes) wird auf der Startseite Ihres Portals in dem Abschnitt angezeigt, in dem die APIs des Projekts aufgeführt sind. Er wird außerdem auf der Seite Einstellungen in der Drop-down-Liste des Tabs APIs angezeigt.

Das Cloud Endpoints-Portal generiert eine Referenzdokumentation für jede RPC-Methode und -Ressource der .proto-Datei. Die mit jeder Methode und Ressource verknüpften Kommentare sind in der Dokumentation enthalten, die in Ihrem Portal angezeigt wird. Der folgende Auszug stammt aus der Datei .proto, die zur Erstellung der Referenzdokumentation für das Beispiel der Bookstore gRPC API aus der Endpoints Portal-Demo verwendet wurde:

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

Die vollständige bookstore.proto-Datei, die in der Demoversion des Endpoints-Portals verwendet wird, befindet sich im Endpoints-Beispiel bookstore-grpc.

SmartDocs regenerieren

Erforderliche Berechtigungen für diese Aufgabe

Stellen Sie die aktualisierte Endpoints-Konfiguration bereit, um SmartDocs neu zu generieren. Die Rolle Dienstkonfigurationsbearbeiter, die für den Dienst erteilt wurde, verfügt über die minimal erforderlichen Berechtigungen zum nochmaligen Bereitstellen der Endpoints-Konfiguration. Informationen zum Zuweisen dieser Rolle finden Sie unter Zugriff auf die API gewähren und widerrufen.

So generieren Sie die Referenzdokumentation neu:

Nehmen Sie die Änderungen an Ihrer Dienstkonfigurationsdatei und/oder Ihrer .proto-Datei vor.
Wenn Sie die Datei .proto geändert haben, kompilieren Sie Ihre Protokollpuffer.
Stellen Sie Ihre .pb und Ihre Dienstkonfigurationsdatei noch einmal bereit, z. B. so:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
Laden Sie Ihre Portalseite neu.

Weitere Informationen zum Befehl finden Sie unter gcloud endpoints services deploy.