Eigene Dokumentation hinzufügen

Neben der Referenzdokumentation für die SmartDocs API können Sie in Ihrem Portal eine eigene Dokumentation für die Nutzer Ihrer API hinzufügen. Auch wenn Sie keine zusätzlichen Dokumentationsseiten für Ihre Nutzer benötigen, müssen Sie trotzdem die in Ihrem Portal angezeigte Beispielanleitung Erste Schritte anpassen, um den Einstieg in Ihre API zu erläutern.

Auf dieser Seite erfahren Sie, wie Sie die Beispielanleitung Erste Schritte ändern und zusätzliche Dokumentationsseiten für das Portal erstellen und anzeigen lassen können. 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:

Vorbereitung

Es wird davon ausgegangen, dass Sie bereits:

Ihre eigene Dokumentation

Damit Ihre eigene Dokumentation im Portal angezeigt wird, müssen Sie die Dateien in einem Git-Repository speichern und die URL für das Git-Repository auf der Seite Einstellungen in Ihrem Portal konfigurieren. Sie können die Dateien für Ihre eigene Dokumentation in eines der folgenden Repositories einfügen:

  • Ein privates Repository in Cloud Source Repositories, das sich im selben Google Cloud-Projekt wie Ihre API befindet.
  • Ein öffentliches Repository in GitHub oder Bitbucket.

Damit das Cloud Endpoints-Portal Ihre eigene Dokumentation findet und diese anzeigen kann, müssen die Dateien und Ordner im Repository eine bestimmte Struktur haben. Im Stammverzeichnis des Repositorys benötigen Sie einen Ordner mit Ihrem Cloud Endpoints-Dienstnamen. Sie können bei Bedarf zusätzliche Unterordner erstellen. Die linke Navigationsleiste enthält Links zu Ihren Ordnern und Dateien. Weitere Informationen finden Sie unter Erforderliche Verzeichnisstruktur.

Sie verwenden Markdown, um die Inhalte der Anleitung Erste Schritte zu bearbeiten und Inhalte für zusätzliche Dokumentationsseiten zu schreiben. Das Endpoints-Portal richtet sich nach der Spezifikation CommonMark sowie der Tabellenerweiterung der GitHub Flavored Markdown-Spezifikation.

Sie können Ihrem Repository auch Bilder hinzufügen und darauf in Ihren Markdown-Dateien verweisen.

Erste Schritte zum Aktualisieren der eigenen Dokumentation

Damit Ihnen der Einstieg leichter fällt, empfehlen wir Ihnen, das Repository endpoints-developer-portal-sample-content auf GitHub zu klonen. Es enthält die folgenden Dateien:

  • Getting Started.md: Die Markdown-Datei, die den Inhalt der Beispielseite Erste Schritte enthält, die im Portal angezeigt wird.
  • Example Page.md: Eine Beispieldatei, die Ihnen den Einstieg in Markdown erleichtern soll.
  • navigation.yaml: Eine Datei, die die Reihenfolge der Seiten und Ordner in der linken Navigationsleiste des Portals beschreibt.

  • add_example_page: Ein Skript, das Folgendes ausführt:

    • Git-Repository in Cloud Source Repositories in Ihrem Google Cloud-Projekt erstellen
    • Lokales Git-Repository im Ordner default-content-repo erstellen
    • Ordner mit demselben Namen wie der Endpoints-Dienst sowie einen Unterordner mit dem Namen Guides erstellen
    • Im Ordner Guides Dateien mit den Namen Example Page.md und Getting Started.md hinzufügen
    • Example Page in die Datei navigation.yaml einfügen
    • Übernimmt diese Änderungen und überträgt sie an das neu erstellte Git-Repository in Cloud Source Repositories.

    Es gibt zwei Versionen des Skripts:

    • Linux- und Mac-Nutzer verwenden add_example_page.sh (Bash-Shell).
    • Windows-Nutzer verwenden add_example_page.ps1 (PowerShell).

    Das Ausführen des Skripts ist optional. Wenn Sie möchten, können Sie stattdessen manuell ein Repository in Cloud Source Repositories oder in einem öffentlichen GitHub- oder Bitbucket-Repository erstellen. Sie müssen die erforderliche Verzeichnisstruktur für Ihre eigene Dokumentation einrichten.

    Bevor Sie das Skript ausführen, sollten Sie die Dokumentation zu den Preisen und Kontingenten für Cloud Source Repositories durchlesen. Wenn Sie das Skript ausgeführt haben und sich später doch dafür entscheiden, lieber ein öffentliches GitHub- oder Bitbucket-Repository zu verwenden, können Sie das Repository aus Cloud Source Repositories löschen.

Startdateien der eigenen Dokumentation abrufen

In diesem Abschnitt wird beschrieben, wie Sie das Skript add_example_page ausführen können.

So rufen Sie die Startdateien der eigenen Dokumentation ab:

  1. Aktivieren Sie die Cloud Source Repositories API:

    1. Öffnen Sie unter "APIs & Dienste" die Seite API-Bibliothek.

      Zur API-Bibliothek

    2. Wählen Sie aus der Projektliste das Projekt aus, in dem sich die API befindet.

    3. Suchen Sie nach der Cloud Source Repositories API und klicken Sie auf die Karte der API, um die zugehörige Informationsseite aufzurufen.

    4. Klicken Sie auf Aktivieren.

  2. Prüfen Sie, ob die gcloud CLI für den Zugriff auf Ihre Daten und Dienste autorisiert ist:

    gcloud auth login

  3. Legen Sie das Standardprojekt fest. Ersetzen Sie im folgenden Befehl YOUR_PROJECT_ID durch die Google Cloud-Projekt-ID, in der Sie die Endpoints API erstellt haben:

    gcloud config set project YOUR_PROJECT_ID

  4. Laden Sie Beispielinhalte, -konfiguration und -skripts herunter:

    git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content

  5. Rufen Sie das Verzeichnis auf, das das Skript enthält:

    cd endpoints-developer-portal-sample-content/scripts

  6. Rufen Sie Ihren Endpoints-Dienstnamen ab:

    gcloud endpoints services list

  7. Führen Sie das Skript mit Ihrem Endpoints-Dienstnamen aus:

    • Linux- und Mac-Nutzer: ./add_example_page.sh SERVICE_NAME
    • Nutzer von Windows: add_example_page.ps1 SERVICE_NAME

    Sobald das Skript abgeschlossen ist, werden URLs für die folgenden Seiten ausgegeben:

    • Die Portaleinstellungen Ihrer API

    • Ihre Git-URL. Dies ist dieselbe URL, die auf der Seite „Cloud Source Repositories“ im Feld Klon-URL angezeigt wird.

  8. Synchronisieren Sie das Repository mit dem Portal:

    1. Markieren und kopieren Sie die erste URL und fügen Sie sie in die Adressleiste des Browsers ein, um die Seite Einstellungen aufzurufen.
    2. Folgen Sie bei der Anmeldung den Eingabeaufforderungen, um zur Seite Einstellungen für die API zu gelangen. Wenn Sie mehrere Konten haben, wählen Sie das Konto aus, das sich im Google Cloud-Projekt befindet, zu dem die API gehört.
    3. Markieren und kopieren Sie die Klon-URL für das Git-Repository und fügen Sie sie in das Feld Benutzerdefinierte Inhaltseinstellungen ein.
    4. Klicken Sie auf Synchronisieren.
    5. Klicken Sie auf Speichern.
    6. Klicken Sie auf die Titelleiste, um zur Landingpage der API-Dokumentation zurückzukehren.

    Klicken Sie in der linken Navigationsleiste auf Beispielseite, um den Inhalt aufzurufen.

  9. Durchsuchen Sie die Inhalte des neu erstellten Repositorys. Rufen Sie in der Google Cloud Console die Seite Quell-Repositories > Quellcode für Ihr Projekt auf.

    Zum Quellcodebrowser

    Der Quellcodebrowser bietet eine Verzeichnisansicht der Repository-Inhalte auf dem aktuellen Commit-Level. Weitere Informationen finden Sie unter Repositories durchsuchen.

Eigene Dokumentation anpassen

Nachdem Sie eine eigene Dokumentation in Cloud Source Repositories erstellt haben, können Sie Inhalte ändern und bei Bedarf Dateien und Ordner einfügen oder löschen. Wenn Sie mit Git noch nicht vertraut sind, finden Sie in der Git-Dokumentation Referenzdokumente sowie Links zu Büchern und Videos.

Inhalt von Getting Started ändern

So ändern Sie den Inhalt von Getting Started:

  1. Rufen Sie im Stammverzeichnis Ihres lokalen Git-Repositorys den Ordner auf, der denselben Namen wie Ihr Endpoints-Dienst trägt. Beispiel:

    cd example-api.example.com

  2. Wechseln Sie zum Ordner, der Getting Started.md enthält:

    cd Guides

  3. Öffnen Sie Getting Started.md in einem Texteditor.

  4. Passen Sie den Inhalt nach Bedarf an, um Ihren Nutzern den Einstieg in die API zu erleichtern.

  5. Speichern Sie die Datei.

  6. Führen Sie mit den Änderungen einen Commit durch:

    git commit -a -m "updated getting started"

  7. Übertragen Sie die Änderungen auf das Repository in Cloud Source Repositories:

    git push

  8. Synchronisieren Sie die aktualisierten Inhalte mit dem Portal:

    1. Gehen Sie zu Ihrem Portal.
    2. Klicken Sie auf Einstellungen .
    3. Klicken Sie auf der Seite Einstellungen auf den Tab APIs und wählen Sie aus der Liste die API aus.
    4. Klicken Sie auf Synchronisieren.
    5. Klicken Sie auf Speichern.

    Wenn Sie in der linken Navigationsleiste auf den Link Erste Schritte klicken, werden im Cloud Endpoints-Portal die aktualisierten Inhalte angezeigt.

Example Page entfernen

So entfernen Sie die Example Page:

  1. Rufen Sie im Stammverzeichnis Ihres lokalen Git-Repositorys den Ordner auf, der denselben Namen wie Ihr Endpoints-Dienst trägt. Beispiel:

    cd example-api.example.com

  2. Öffnen Sie die Datei navigation.yaml in einem Texteditor.

  3. Löschen Sie im Abschnitt ordering die Zeile mit Example Page.

  4. Speichern Sie die Datei.

  5. Entfernen Sie die Datei Example Page.md aus Git:

    git rm ‘Guides/Example Page.md'

  6. Wenden Sie Ihre Änderungen an:

    git commit -a -m "removed example page"

  7. Übertragen Sie die Änderungen auf das Repository in Cloud Source Repositories:

    git push

  8. Synchronisieren Sie die aktualisierten Inhalte mit dem Portal:

    1. Gehen Sie zu Ihrem Portal.
    2. Klicken Sie auf Einstellungen .
    3. Klicken Sie auf der Seite Einstellungen auf den Tab APIs und wählen Sie aus der Liste die API aus.
    4. Klicken Sie auf Synchronisieren.
    5. Klicken Sie auf Speichern.

Example Page befindet sich nicht mehr in der linken Navigationsleiste.

Example Page umbenennen

So benennen Sie die Example Page um:

  1. Rufen Sie im Stammverzeichnis Ihres lokalen Git-Repositorys den Ordner auf, der denselben Namen wie Ihr Endpoints-Dienst trägt. Beispiel:

    cd example-api.example.com

  2. Öffnen Sie die Datei navigation.yaml in einem Texteditor.

  3. Ändern Sie im Abschnitt ordering den Text Example Page in den Titel Ihrer Anleitung. Der hier angegebene Name muss mit dem tatsächlichen Dateinamen im Verzeichnis Guides übereinstimmen.

  4. Speichern Sie die Datei.

  5. Geben Sie der Datei Example Page.md in Git einen neuen Namen.

    git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'

  6. Passen Sie die Inhalte der umbenannten Datei nach Bedarf an.

  7. Führen Sie mit den Änderungen einen Commit durch:

    git commit -a -m "removed example page"

  8. Übertragen Sie die Änderungen auf das Repository in Cloud Source Repositories:

    git push

  9. Synchronisieren Sie die aktualisierten Inhalte mit dem Portal:

    1. Gehen Sie zu Ihrem Portal.
    2. Klicken Sie auf Einstellungen .
    3. Klicken Sie auf der Seite Einstellungen auf den Tab APIs und wählen Sie aus der Liste die API aus.
    4. Klicken Sie auf Synchronisieren.
    5. Klicken Sie auf Speichern.

Die umbenannte Seite wird in der linken Navigationsleiste angezeigt.

Erforderliche Verzeichnisstruktur

Damit das Cloud Endpoints-Portal die benutzerdefinierten Inhalte findet und diese anzeigen kann, müssen die Dateien und Ordner im Repository eine bestimmte Struktur haben.

Im Stammverzeichnis des Repositorys muss sich ein Ordner mit dem Namen Ihres Endpoints-Dienstes befinden. Diese Struktur bietet Ihnen die Möglichkeit, ein Repository für mehrere APIs zu verwenden, indem Sie für jede API auf oberster Ebene einen separaten Ordner ansiedeln.

Mit Unterordnern im Dienstordner können Sie verwandte Seiten in einem Abschnitt gruppieren. Diese Ordner können weitere Unterordner enthalten. Die Titel der Ordner und die Dateinamen werden für die Navigation verwendet. Beispielsweise wird eine Datei namens Getting Started.md in der linken Navigationsleiste als Getting Started angezeigt. In dem Ordner, der nach dem Endpoints-Dienstnamen benannt ist, muss eine Datei namens navigation.yaml vorhanden sein. In dieser Datei ist angegeben, wie die Inhalte in der linken Navigationsleiste des Portals angezeigt werden sollen. Standardmäßig sieht diese so aus:

ordering:
- Introduction
- Guides
- API Reference
- Resources

folders:
  Guides:
    ordering:
    - Getting Started
    - Example Page

Die erste Liste ordering gibt die Reihenfolge an, in der die Einträge auf dieser Ebene angezeigt werden sollen. In der standardmäßigen navigation.yaml-Datei ist zum Beispiel festgelegt, dass die Seite Introduction zuerst angezeigt wird, gefolgt vom Abschnitt Guides und so weiter.

Introduction, API Reference und Resources sind spezielle Abschnitte, die nicht aus navigation.yaml entfernt werden dürfen. Sie können jedoch ihre Reihenfolge ändern.

Für jeden Ordner und jede Seite sollte in der Konfiguration des übergeordneten folders in navigation.yaml eine entsprechende Konfiguration vorhanden sein. Fehlt diese, wird die Seite oder der Ordner nicht im Portal angezeigt. In der standardmäßigen navigation.yaml-Datei enthält der Schlüssel folders beispielsweise einen Unterschlüssel namens Guides, da es einen Ordner mit demselben Namen gibt.

Bilder hinzufügen

Sie können dem Git-Repository für benutzerdefinierte Inhalte Bilder hinzufügen und darauf in Ihren Markdown-Dateien verweisen. Wenn Sie die Bilder und darauf verweisende Markdown-Dateien in dem Verzeichnis ablegen, das nach dem Namen des Endpoints-Diensts benannt ist, können Sie mit einer relativen URL (beginnend mit einem /) auf die Bilder verweisen.

Angenommen, Sie haben die folgende Verzeichnisstruktur:

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

Sie können get-started.md das Bild images/example.jpg mit folgendem Markup hinzufügen:

    ![alt-text](/images/example.jpg "Optional title")

Sie können an anderer Stelle gehostete Bilder mit der Standard-Markdown-Syntax und der vollständigen Bild-URL einfügen:

    ![alt-text](https://example.com/image.png "Optional title")

Das Portal unterstützt folgende Bildtypen:

  • BMP
  • GIF
  • JPEG
  • PNG
  • TIFF
  • WEBP

Benutzerdefinierte Inhaltsbeschränkungen

Auf dem Portal gelten für benutzerdefinierte Inhalte die folgenden Beschränkungen:

  • Maximal 200 Markdown-Seiten pro API.
  • Maximal 200 Bilder pro API.
  • Maximal 4 MiB pro Bild.

Nächste Schritte