Modifier Cloud Endpoints pour utiliser OpenAPI 3.x

Cette page explique comment utiliser une spécification OpenAPI 3.x lors de la configuration d'Endpoints.

Avant de commencer

  • Vérifiez que vous disposez d'une instance Endpoints existante configurée avec une spécification OpenAPI 2.0.
  • Installez la CLI gcloud. Pour en savoir plus, consultez Installer Google Cloud CLI.

Modifier votre configuration Endpoints pour utiliser OpenAPI 3.x

Pour modifier une configuration OpenAPI 2.0 Endpoints existante afin d'utiliser OpenAPI 3.x, procédez comme suit.

Afficher l'historique des déploiements

Pour afficher l'historique des déploiements :

  1. Dans la console Google Cloud , accédez à la page Endpoints > Services.

    Accédez à la page Services Endpoints

  2. Dans la liste des projets, sélectionnez un projet.

  3. Si vous avez plusieurs API, sélectionnez-en une dans la liste.

  4. Pour afficher une liste des déploiements de configuration de service, cliquez sur l'onglet Historique de déploiement. La liste affiche :

    • l'ID de configuration ;
    • la date à laquelle la configuration de service a été déployée ;
    • l'utilisateur qui a déployé la configuration de service.

Afficher la configuration du service

Dans l'onglet Historique des déploiements, sélectionnez le déploiement le plus récent dans la liste. Le contenu du fichier de configuration de service déployé s'affiche.

Convertir le document OpenAPI au format OpenAPI 3.x

Convertissez votre document OpenAPI 2.0 au format OpenAPI 3.x. Vous pouvez utiliser un outil compatible avec cette conversion vers OpenAPI 3.x. Par exemple, Swagger Editor fournit un utilitaire de conversion.

Après la conversion initiale au format OpenAPI 3.x, appliquez manuellement les modifications supplémentaires au document pour l'aligner sur OpenAPI 3.x et assurer la compatibilité avec les extensions et les fonctionnalités Endpoints.

Le tableau suivant décrit les modifications requises :

Fonctionnalité OpenAPI 2.0 OpenAPI 3.x Description de la modification
Clé API securityDefinitions securitySchemes Les clés API utilisent la compatibilité avec les clés API OpenAPI prêtes à l'emploi. Les outils de conversion gèrent généralement cela automatiquement. Aucune modification manuelle n'est requise.
Authentification JWT x-google-audiences, etc. x-google-auth Dans les extensions OpenAPI 2.0, vous définissez la configuration OAuth avec des extensions individuelles sur une instance securityDefinition. Les outils de conversion convertissent l'instance de schéma de sécurité en #/components/securitySchemes et conservent les extensions. Modifiez manuellement ces extensions pour qu'elles soient des enfants de x-google-auth et supprimez le préfixe x-google-. Les valeurs restent les mêmes.
Quota x-google-management, x-google-quota x-google-api-management, x-google-quota Dans les extensions OpenAPI 2.0, vous définissez les métriques et le quota dans x-google-management et les associez avec x-google-quota. Les outils de conversion laissent ces extensions en place. Déplacez manuellement les métriques et la configuration du quota de x-google-management vers x-google-api-management. Modifiez la configuration pour utiliser les clés YAML et supprimez valueType, metricKind et unit. Supprimez metricCosts des instances de x-google-quota.
Backends x-google-backend x-google-api-management, x-google-backend Dans les extensions OpenAPI 2.0, vous définissez les backends dans x-google-backend. La configuration s'applique là où elle est définie. Dans les extensions OpenAPI 3.x, vous définissez le backend dans x-google-api-management, puis vous l'appliquez avec x-google-backend. Les outils de conversion laissent cette extension en place. Déplacez manuellement la configuration vers x-google-api-management. Modifiez les instances de x-google-backend pour faire référence à cette configuration.
Points de terminaison x-google-endpoints x-google-endpoint, servers Dans les extensions OpenAPI 2.0, vous définissez la configuration des points de terminaison dans x-google-endpoints. Dans les extensions OpenAPI 3.x, vous utilisez x-google-endpoint, mais il s'agit d'une extension sur servers plutôt qu'à la racine. Les outils de conversion laissent cette extension en place. Déplacez manuellement cette valeur vers servers et supprimez le champ name. Exemple : 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
Noms des API x-google-api-name x-google-api-management Dans les extensions OpenAPI 2.0, vous définissez les noms d'API dans x-google-api-name. Dans les extensions OpenAPI 3.x, vous utilisez un champ apiName dans x-google-api-management. Déplacez manuellement cette configuration vers x-google-api-management.
Autoriser tout le trafic x-google-allow NON COMPATIBLE Supprimez-le du document OpenAPI. Endpoints n'est pas compatible avec cette fonctionnalité dans OpenAPI 3.x.

Redéployer la configuration de votre service

Lorsque vous modifiez un élément de votre document OpenAPI, veillez à le déployer à nouveau afin que Cloud Endpoints dispose de la version la plus récente de la configuration de service de votre API. Si vous avez déjà déployé ESP en ayant défini l'option rollout sur managed, vous n'avez pas besoin de redéployer ni de redémarrer ESP. Cette option configure ESP pour qu'il utilise la dernière configuration de service déployée. Si cette option est spécifiée, jusqu'à 5 minutes après le déploiement d'une nouvelle configuration de service, ESP détecte la modification et commence à l'utiliser automatiquement. Nous vous recommandons de spécifier cette option plutôt qu'un ID de configuration spécifique à utiliser par ESP.

Pour déployer votre document OpenAPI, procédez comme suit :

  1. Remplacez le répertoire par l'emplacement contenant votre document OpenAPI.

  2. Validez l'ID de projet renvoyé par la commande suivante, afin de vous assurer que le service est créé dans le projet correct.

    gcloud config list project

    Si vous devez changer le projet par défaut, exécutez la commande suivante et remplacez YOUR_PROJECT_ID par l'ID du projet Google Cloud dans lequel vous souhaitez créer le service :

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. Exécutez la commande suivante et remplacez YOUR_OPENAPI_DOCUMENT par le nom du document OpenAPI décrivant votre API :

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

La première fois que vous exécutez la commande ci-dessus, Service Management crée un nouveau service Cloud Endpoints dans le projet par défaut avec un nom correspondant au texte que vous avez spécifié dans le champ host de votre document OpenAPI, puis transfère la configuration de votre service.

Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Si l'opération réussit, une ligne semblable à la suivante affiche l'ID de configuration et le nom du service :

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Dans l'exemple ci-dessus, 2017-02-13r0 correspond à l'ID de configuration du service et echo-api.endpoints.example-project-12345.cloud.goog au nom du service.

Une fois le déploiement réussi, vous pouvez consulter l'API sur la page Endpoints > Services de la console Google Cloud .

Si vous recevez un message d'erreur, consultez la section Résoudre des problèmes de déploiement de la configuration Endpoints.

Étapes suivantes