SmartDocs aktualisieren

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 in der von Cloud Endpoints Frameworks erstellten Datei openapi.json zum Generieren von SmartDocs verwendet.
Wie SmartDocs neu generiert wird Für jede Aufgabe wird die Berechtigung oder Rolle für die Identitäts- und Zugriffsverwaltung angegeben, die mindestens für die Durchführung der Aufgabe erforderlich ist. 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

Fügen Sie die API-Verwaltung wie hier beschrieben hinzu:

Endpoints Frameworks erstellt ein OpenAPI-Dokument für Ihre API. Immer dann, wenn Sie das OpenAPI-Dokument in Ihrem Endpoints-Dienst bereitstellen, 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

Fügen Sie die API-Verwaltung wie hier beschrieben hinzu:

Endpoints Frameworks erstellt für die API ein OpenAPI-Dokument im JSON-Format. Wenn Sie das OpenAPI-Dokument mithilfe von gcloud endpoints services deploy bereitstellen, generiert SmartDocs eine aktualisierte API-Referenzdokumentation für Ihr Portal, die auf dem von Endpoints Frameworks erstellten OpenAPI-Dokument beruht.

Endpoints Frameworks fügt in das OpenAPI-Dokument, das es für Ihre API erstellt, keine Beschreibungen ein. Bevor Sie den Nutzern Ihrer API die URL Ihres Portals mitteilen, sollten Sie der API, den Methoden und den Parametern im OpenAPI-Dokument Beschreibungen hinzufügen.

Sollten Sie mit OpenAPI noch nicht vertraut sein, werfen Sie einen Blick auf die Swagger-Website mit Grundstrukturen. Dort finden Sie ein einfaches OpenAPI-Beispieldokument. Außerdem werden die einzelnen Abschnitte der Datei kurz erläutert. Weitere Informationen finden Sie in der OpenAPI-Spezifikation.

Wie im Abschnitt "Metadaten" beschrieben, kann der Wert für das Feld descriptiondescription mehrere Zeilen enthalten und unterstützt GitHub Flavored Markdown.

Damit Ihre Nutzer besser verstehen, wie die Methoden in der API eingesetzt werden können, fügen Sie dem descriptionParameterabschnitt und dem Anfragetext das Feld description hinzu.

Das OpenAPI-Dokument enthält etwa Folgendes:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

Die Werte für diese Felder werden so im Portal angezeigt:

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.
host: Der Wert für den Host, der auch der Name des Endpoints-Dienstes ist, wird auf der Startseite des Portals in dem Abschnitt angezeigt, in dem die APIs des Projekts aufgeführt sind. Sie finden ihn auch auf der Seite Einstellungen in der Drop-down-Liste des Tabs APIs.
version: Die Hauptversionsnummer wird in der URL des API-Portals verwendet.

Sie können den Wert im Feld title ändern und das Feld description für die API hinzufügen. Beispiel:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

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 Änderungen an der Datei openapi.json vor, die von Endpoints Frameworks generiert wurde.

Stellen Sie openapi.json neu bereit:

gcloud endpoints services deploy openapi.json

Laden Sie Ihre Portalseite neu.
Speichern Sie die geänderte Datei openapi.json an einem Ort, an dem sie nicht überschrieben werden kann, wenn Sie anschließend die Datei openapi.json neu generieren müssen. Wenn Sie Änderungen an Ihrer API vornehmen und die Datei openapi.json neu generieren, müssen Sie die Änderungen in der neu generierten Datei openapi.json mit den Änderungen, die Sie zuvor ausgeführt haben, zusammenführen.

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