Mettre à jour des SmartDocs

Avant de fournir l'URL de votre portail aux utilisateurs de votre API, vous devez vous assurer que la documentation de référence de l'API SmartDocs est correcte et que l'API se comporte comme indiqué. Lorsque vous passez en revue la documentation de référence générée et le test, il est possible que vous souhaitiez modifier certains éléments.

Cette page décrit :

  • la documentation de référence de l'API SmartDocs ;
  • comment SmartDocs exploite les champs du document OpenAPI pour générer des SmartDocs ;
  • comment régénérer les SmartDocs.
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 :

Prérequis

Dans cette page, nous partons du principe que vous avez déjà créé votre portail.

À propos de la documentation de référence de l'API SmartDocs

Chaque fois que vous déployez un document OpenAPI sur votre service Endpoints, SmartDocs génère une documentation de référence relative à l'API pour votre portail. L'interface utilisateur SmartDocs est basée sur Angular Material, une bibliothèque de composants d'interface utilisateur aux performances optimales. Les développeurs peuvent consulter la documentation de référence SmartDocs de votre API et utiliser le widget Essayer cette API pour interagir avec votre API sans quitter la documentation.

À propos des champs utilisés pour générer des SmartDocs

Votre document OpenAPI comprend une partie semblable à ce qui suit :

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"

Les valeurs des champs ci-dessus sont affichées comme suit dans le portail :

  • title : la valeur du titre est affichée sur la page d'accueil de votre portail dans la section répertoriant les API du projet, sur la page d'accueil de l'API (avec le mot documentation ajouté en complément) et dans la barre de titre de l'API.

  • description : la valeur de la description est affichée en petit sous le titre de la page d'accueil de l'API.

  • host : la valeur de l'hôte (qui est aussi le nom de votre service Cloud Endpoints) est affichée sur la page d'accueil de votre portail dans la section répertoriant les API du projet, ainsi que sur la page Paramètres dans la liste déroulante affichée dans l'onglet API.

  • version : le numéro de version majeure est utilisé dans l'URL du portail de l'API.

Le portail Endpoints génère une documentation de référence pour chaque point de terminaison individuel répertorié dans la section paths du document OpenAPI. Les extraits suivants proviennent du fichier OpenAPI utilisé pour générer la documentation de référence du point de terminaison echo de l'exemple d'API Endpoints présenté dans la démonstration du portail Endpoints :

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: []

Le paramètre du point de terminaison echo est défini dans la section suivante : 

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

La version complète du fichier openapi.yaml utilisé dans la démonstration du portail Endpoints se trouve dans l'exemple Endpoints getting-started.

Il est recommandé de toujours inclure le champ description dans les définitions de propriété et dans toutes les autres sections du document OpenAPI. Le champ description peut contenir plusieurs lignes et est compatible avec GitHub Flavored Markdown. Par exemple, le code suivant crée une liste à puces sur la page d'accueil de l'API dans un portail :

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"

Regénérer des SmartDocs

Pour regénérer la documentation de référence, procédez comme suit :

  1. Modifiez le document OpenAPI.

  2. Redéployez votre document OpenAPI (dénommé openapi.yaml dans la commande suivante) :

    gcloud endpoints services deploy openapi.yaml

  3. Actualisez la page de votre portail.

Pour en savoir plus sur cette commande, consultez la page gcloud endpoints services deploy.