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 in Ihrem OpenAPI-Dokument für die SmartDocs-Generierung verwendet
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

Jedes Mal, wenn Sie ein OpenAPI-Dokument für Ihren Cloud Endpoints-Dienst bereitstellen, wird von SmartDocs eine API-Referenzdokumentation für Ihr Portal generiert. 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 im Bereich API testen mit Ihrer API interagieren, ohne die API-Dokumentation zu verlassen.

Felder für die SmartDocs-Generierung

Ihr OpenAPI-Dokument enthält etwa Folgendes:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

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.
description: Der Wert für die Beschreibung wird in kleiner Schrift unter dem Titel auf der API-Startseite angezeigt.
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.

Das Endpoints-Portal generiert eine Referenzdokumentation für jeden einzelnen Endpunkt, der im Abschnitt paths des OpenAPI-Dokuments aufgeführt ist. Die folgenden Auszüge stammen aus dem OpenAPI-Dokument, das verwendet wird, um die Referenzdokumentation für den echo-Endpoint in der Endpoints-Beispiel-API in der Endpoints-Portal-Demo zu erzeugen:

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []

Der Parameter für den Endpunkt echo wird im folgenden Abschnitt definiert:

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"

Die vollständige openapi.yaml-Datei, die in der Demoversion des Endpoints-Portals verwendet wird, befindet sich im Endpoints-Beispiel getting-started.

Fügen Sie als Best Practice immer das Feld description in die Attributdefinitionen und in alle anderen Abschnitte des OpenAPI-Dokuments ein. Das Feld description kann mehrere Zeilen enthalten und unterstützt GitHub Flavored Markdown. So wird beispielsweise eine Liste mit Aufzählungszeichen auf der API-Startseite in einem Portal erstellt:

swagger: "2.0"
info:
  description: "A simple API to help you learn about Cloud Endpoints.

  * item 1

  * item 2"
title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

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 am OpenAPI-Dokument vor.
Stellen Sie das OpenAPI-Dokument noch einmal bereit (im folgenden Befehl als openapi.yaml bezeichnet):
```
gcloud endpoints services deploy openapi.yaml
```
Laden Sie Ihre Portalseite neu.

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