Ajouter de la documentation personnalisée

En complément de la documentation de référence sur l'API SmartDocs, vous pouvez ajouter à votre portail une documentation personnalisée susceptible d'être utile aux utilisateurs de votre API. Même si vous n'avez pas besoin de fournir à vos utilisateurs des pages de documentation supplémentaires, vous devez mettre à jour l'exemple de guide de démarrage affiché sur votre portail, expliquant comment débuter avec votre API.

Cette page explique comment modifier l'exemple de Guide de démarrage, et comment créer et afficher des pages de documentation supplémentaires pour votre portail. Pour chaque tâche, le ou les rôles Identity and Access Management minimaux requis pour l'exécution sont fournis. Pour en savoir plus sur les autorisations IAM, consultez les pages suivantes :

Prerequisites

Dans cette page, nous partons du principe que vous avez déjà :

À propos de la documentation personnalisée

Pour afficher la documentation personnalisée sur votre portail, vous devez stocker les fichiers dans un dépôt Git et configurer l'URL de ce dépôt sur la page Paramètres de votre portail. Vous pouvez ajouter les fichiers de votre documentation personnalisée dans deux endroits :

  • Un dépôt privé dans Cloud Source Repositories, qui se trouve dans le même projet Google Cloud que votre API.
  • Un dépôt public dans GitHub ou Bitbucket

Pour que le portail Cloud Endpoints trouve et affiche votre documentation personnalisée, les fichiers et les dossiers de votre dépôt doivent être organisés selon une structure spécifique. À la racine du dépôt, vous avez besoin d'un dossier avec le nom de votre service Cloud Endpoints. Vous pouvez créer d'autres sous-dossiers si nécessaire. La barre de navigation de gauche contient des liens vers vos dossiers et fichiers. Pour en savoir plus, consultez la section Structure de répertoires requise.

Markdown vous permet de modifier le contenu du Guide de démarrage et d'écrire le contenu des pages de documentation supplémentaires. Le portail Endpoints suit la spécification CommonMark ainsi que l'extension de table de la spécification GitHub Flavored Markdown.

Vous pouvez également ajouter des images à votre dépôt et les référencer à partir de vos fichiers Markdown.

Démarrer la mise à jour de la documentation personnalisée

Pour vous aider à démarrer, nous vous recommandons de cloner le dépôt endpoints-developer-portal-sample-content sur GitHub, qui contient les fichiers suivants :

  • Getting Started.md : fichier Markdown qui comprend le contenu de la page d'exemple de guide de démarrage qui s'affiche dans votre portail.
  • Example Page.md : exemple de fichier pour vous aider à démarrer avec Markdown.
  • navigation.yaml : fichier décrivant l'ordre des pages et des dossiers dans la barre de navigation de gauche de votre portail.

  • add_example_page : script qui effectue les opérations suivantes :

    • Création d'un dépôt Git dans Cloud Source Repositories dans votre projet Google Cloud
    • Création d'un dépôt Git local dans le dossier default-content-repo
    • Création d'un dossier portant le même nom que votre service Endpoints et création d'un sous-dossier appelé Guides
    • Ajout de fichiers appelés Example Page.md et Getting Started.md dans le dossier Guides
    • Ajout de Example Page au fichier navigation.yaml
    • Validation et transfert de ces modifications dans le dépôt Git nouvellement créé dans Cloud Source Repositories

    Il existe deux versions du script :

    • add_example_page.sh (shell Bash) pour les utilisateurs Linux et Mac
    • add_example_page.ps1 (PowerShell) pour les utilisateurs Windows

    L'exécution du script est facultative. Si vous le souhaitez, vous pouvez créer manuellement un dépôt dans Cloud Source Repositories ou dans un dépôt public GitHub ou Bitbucket. Il vous suffit de configurer la structure de répertoires requise pour votre documentation personnalisée.

    Avant d'exécuter le script, vous souhaiterez peut-être consulter la documentation relative aux tarifs et quotas de Cloud Source Repositories. Si vous exécutez le script, puis décidez que vous préférez utiliser un dépôt GitHub ou Bitbucket public, vous pouvez supprimer le dépôt de Cloud Source Repositories.

Obtenir les fichiers de démarrage de la documentation personnalisée

Cette section présente la configuration à mettre en place pour pouvoir exécuter le script add_example_page.

Pour obtenir les fichiers de démarrage de la documentation personnalisée, procédez comme suit :

  1. Activez l'API de Cloud Source Repositories.

    1. Dans "API et services", accédez à la page Bibliothèque d'API.

      Accéder à la bibliothèque d'API

    2. Dans la liste des projets, sélectionnez le projet dans lequel se trouve votre API.

    3. Recherchez l'API Cloud Source Repositories et cliquez sur sa carte pour afficher sa page d'informations.

    4. Cliquez sur Activer.

  2. Assurez-vous que gcloud CLI est autorisée à accéder à vos données et services:

    gcloud auth login

  3. Définissez le projet par défaut. Dans la commande ci-dessous, remplacez YOUR_PROJECT_ID par l'ID du projet Google Cloud dans lequel vous avez créé votre API Endpoints :

    gcloud config set project YOUR_PROJECT_ID

  4. Téléchargez l'exemple de contenu, la configuration et les scripts :

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

  5. Accédez au répertoire contenant le script :

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

  6. Affichez le nom de votre service Cloud Endpoints :

    gcloud endpoints services list

  7. Exécutez le script avec le nom de votre service Cloud Endpoints :

    • Utilisateurs Linux et Mac : ./add_example_page.sh SERVICE_NAME
    • Utilisateurs Windows : add_example_page.ps1 SERVICE_NAME

    Une fois le script terminé, les URL sont imprimées aux emplacements suivants :

    • Les paramètres du portail de votre API

    • Votre URL Git Il s'agit de la même URL que celle affichée dans le champ Cloner l'URL sur la page Cloud Source Repositories.

  8. Synchronisez le dépôt sur votre portail :

    1. Mettez en surbrillance et copiez la première URL, puis collez-la dans la barre d'adresse de votre navigateur pour accéder à la page Paramètres.
    2. Suivez les invites de connexion pour accéder à la page Paramètres de votre API. Si vous avez plusieurs comptes, veillez à choisir le compte du projet Google Cloud propriétaire de l'API.
    3. Mettez en surbrillance et copiez l'URL clonée de votre dépôt Git, puis collez-la dans le champ Paramètres de contenu personnalisés.
    4. Cliquez sur Synchroniser.
    5. Cliquez sur Enregistrer.
    6. Pour revenir à la page d'accueil de la documentation de l'API, cliquez sur la barre de titre.

    Dans la barre de navigation de gauche, cliquez sur Page d'exemple pour afficher le contenu.

  9. Parcourez le contenu du dépôt que vous venez de créer. Dans la console Google Cloud, accédez à la page Source Repositories > Code source de votre projet.

    Accéder au navigateur du code source

    Le navigateur du code source affiche le répertoire du contenu du dépôt au niveau du commit le plus récent. Pour en savoir plus, consultez la page Parcourir les dépôts.

Modifier la documentation personnalisée

Maintenant que vous disposez d'une documentation personnalisée dans Cloud Source Repositories, vous pouvez en modifier le contenu, et ajouter ou supprimer des fichiers et des dossiers selon vos besoins. Si vous débutez dans l'utilisation de Git, la documentation Git contient une documentation de référence, ainsi que des liens vers des livres et des vidéos.

Modifier le contenu de Getting Started

Pour modifier le contenu de Getting Started, procédez comme suit :

  1. Depuis la racine de votre dépôt Git local, accédez au dossier portant le même nom que votre service Cloud Endpoints. Exemple :

    cd example-api.example.com

  2. Accédez au dossier contenant Getting Started.md :

    cd Guides

  3. Ouvrez Getting Started.md dans un éditeur de texte.

  4. Modifiez le contenu si nécessaire pour aider vos utilisateurs à commencer à utiliser votre API.

  5. Enregistrez le fichier.

  6. Validez vos modifications :

    git commit -a -m "updated getting started"

  7. Transférez les modifications à votre dépôt dans Cloud Source Repositories :

    git push

  8. Synchronisez le contenu mis à jour sur votre portail :

    1. Accédez à votre portail.
    2. Cliquez sur Paramètres .
    3. Sur la page Paramètres, cliquez sur l'onglet API et sélectionnez votre API dans la liste.
    4. Cliquez sur Synchroniser.
    5. Cliquez sur Enregistrer.

    Lorsque vous cliquez sur le lien Premiers pas dans la barre de navigation de gauche, le portail Endpoints affiche le contenu mis à jour.

Supprimer Example Page

Pour supprimer Example Page, procédez comme suit :

  1. Depuis la racine de votre dépôt Git local, accédez au dossier portant le même nom que votre service Cloud Endpoints. Exemple :

    cd example-api.example.com

  2. Ouvrez le fichier navigation.yaml dans un éditeur de texte.

  3. Dans la section ordering, supprimez la ligne contenant Example Page.

  4. Enregistrez le fichier.

  5. Supprimez le fichier Example Page.md de Git :

    git rm ‘Guides/Example Page.md'

  6. Validez vos modifications :

    git commit -a -m "removed example page"

  7. Transférez les modifications à votre dépôt dans Cloud Source Repositories :

    git push

  8. Synchronisez le contenu mis à jour sur votre portail :

    1. Accédez à votre portail.
    2. Cliquez sur Paramètres .
    3. Sur la page Paramètres, cliquez sur l'onglet API et sélectionnez votre API dans la liste.
    4. Cliquez sur Synchroniser.
    5. Cliquez sur Enregistrer.

Example Page ne figure plus dans la barre de navigation de gauche.

Renommer Example Page

Pour renommer Example Page, procédez comme suit :

  1. Depuis la racine de votre dépôt Git local, accédez au dossier portant le même nom que votre service Cloud Endpoints. Exemple :

    cd example-api.example.com

  2. Ouvrez le fichier navigation.yaml dans un éditeur de texte.

  3. Dans la section ordering, remplacez Example Page par le titre de votre guide. Le nom indiqué ici doit correspondre au nom de fichier réel dans le répertoire Guides.

  4. Enregistrez le fichier.

  5. Renommez le fichier Example Page.md dans Git.

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

  6. Modifiez le contenu du fichier renommé si nécessaire.

  7. Validez vos modifications :

    git commit -a -m "removed example page"

  8. Transférez les modifications à votre dépôt dans Cloud Source Repositories :

    git push

  9. Synchronisez le contenu mis à jour sur votre portail :

    1. Accédez à votre portail.
    2. Cliquez sur Paramètres .
    3. Sur la page Paramètres, cliquez sur l'onglet API et sélectionnez votre API dans la liste.
    4. Cliquez sur Synchroniser.
    5. Cliquez sur Enregistrer.

La page renommée est affichée dans la barre de navigation de gauche.

Structure de répertoire requise

Pour que le portail Endpoints trouve et affiche votre contenu personnalisé, les fichiers et les dossiers de votre dépôt doivent être organisés selon une structure spécifique.

Un dossier portant le nom de votre service Endpoints doit être présent à la racine du dépôt. Cette structure vous permet d'utiliser un dépôt pour plusieurs API, en disposant de dossiers distincts au niveau racine pour chaque API.

Les sous-dossiers de votre dossier de service vous permettent de regrouper les pages associées dans une section et peuvent contenir d'autres sous-dossiers. Le titre des dossiers et les noms de fichiers sont utilisés dans la navigation. Par exemple, un fichier nommé Getting Started.md apparaît sous cette forme dans la barre de navigation de gauche : Getting Started. Dans le dossier nommé d'après le nom de votre service Endpoints, vous devez disposer d'un fichier appelé navigation.yaml. Ce fichier définit vos choix en matière d'affichage de contenu dans la barre de navigation de gauche de votre portail. L'affichage par défaut ressemble à ceci :

ordering:
- Introduction
- Guides
- API Reference
- Resources

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

La première liste ordering spécifie l'ordre dans lequel vous voulez que les entrées s'affichent à ce niveau. Par exemple, le fichier par défaut navigation.yaml spécifie que la page Introduction apparaît en premier, suivie de la section Guides, et ainsi de suite.

Introduction, API Reference et Resources sont des sections spéciales. Vous ne devez pas les supprimer du fichier navigation.yaml, mais vous pouvez en modifier l'ordre.

Chaque dossier et chaque page doivent avoir une configuration correspondante dans la configuration folders du parent dans navigation.yaml. En cas d'omission, la page ou le dossier n'apparaît pas sur votre portail. Par exemple, dans le fichier navigation.yaml par défaut, la clé folders contient une sous-clé nommée Guides, car il existe un dossier du même nom.

Ajouter des images

Vous pouvez ajouter des images au dépôt Git de contenu personnalisé et les référencer dans vos fichiers Markdown. Si vous placez les images et tout fichier Markdown les référençant dans le répertoire correspondant au nom de votre service Endpoints, vous pouvez référencer les images avec une URL relative (commençant par un caractère /).

Par exemple, supposons que vous ayez la structure de répertoires suivante :

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

Vous pouvez ajouter l'image images/example.jpg à get-started.md avec le balisage suivant :

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

Vous pouvez ajouter des images hébergées ailleurs en utilisant la syntaxe standard Markdown et l'URL complète de l'image comme suit :

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

Le portail est compatible avec les types d'images suivants :

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

Limiter le contenu personnalisé

Le portail définit les limites suivantes pour le contenu personnalisé :

  • Maximum de 200 pages Markdown par API
  • Maximum de 200 images par API
  • Taille maximale de 4 Mio par image

Étapes suivantes