Cette page a été traduite par l'API Cloud Translation.

Modifier une passerelle pour utiliser OpenAPI 3.x

Cette page explique comment modifier une passerelle d'API existante pour qu'elle utilise une spécification OpenAPI 3.x pour sa configuration d'API.

Avant de commencer

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

Modifier une configuration d'API pour utiliser OpenAPI 3.x

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

Trouver la configuration actuelle de l'API

Recherchez la configuration d'API associée à votre passerelle.

Décrivez votre instance API Gateway :

gcloud api-gateway gateways describe GATEWAY_ID --project=PROJECT_ID --location=GATEWAY_LOCATION

Remplacez les éléments suivants :

GATEWAY_ID : ID de votre passerelle.
PROJECT_ID : ID de votre projet Google Cloud .
GATEWAY_LOCATION : emplacement de votre passerelle.

Le résultat affiche le chemin d'accès apiConfig, par exemple :

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-gateway-config
createTime: '2025-03-25T02:49:58.641650649Z'
defaultHostname: my-gateway-a1b2c3d4.uc.gateway.dev
displayName: My gateway
name: projects/my-project/locations/us-west1/gateways/my-new-gateway
state: ACTIVE
updateTime: '2025-03-25T02:51:52.674308428Z'

Obtenir le document OpenAPI

Pour obtenir le document OpenAPI de la configuration d'API que vous avez identifiée :

Décrivez la configuration de l'API :

gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID --project=PROJECT_ID --view=FULL

Remplacez les éléments suivants :

CONFIG_ID : ID de votre configuration d'API.
API_ID : ID de votre API.
PROJECT_ID : ID de votre projet Google Cloud .

Le résultat affiche la section openapiDocuments, qui contient le contenu encodé en base64 de votre document OpenAPI :

createTime: '2024-02-16T21:11:36.293169474Z'
displayName: my-api-config
gatewayServiceAccount: projects/-/serviceAccounts/api-gateway-sa@my-sandbox.iam.gserviceaccount.com
name: projects/my-project-id/locations/global/apis/my-api/configs/my-gateway-config
openapiDocuments:
-   document:
    contents: IyBvc...
    path: apigateway-config.yaml
serviceConfigId: my-api-config-0a1fjkfeb7t8z
state: ACTIVE
updateTime: '2024-02-16T21:13:45.626771120Z'

Décoder le document OpenAPI

Pour décoder le contenu du document OpenAPI encodé en base64 :

Décodez la valeur contents :

echo 'IyBvc...' | base64 -d

Remplacez IyBvc... par la valeur contents réelle de l'étape précédente.

La sortie affiche votre document OpenAPI 2.0, par exemple :

swagger: '2.0'
info:
  title: API_ID
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0

Convertir le document OpenAPI au format OpenAPI 3.x

Vous pouvez utiliser un outil pour convertir votre document OpenAPI 2.0 en 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 d'API Gateway. Pour en savoir plus sur les extensions OpenAPI 3.x compatibles dans API Gateway, consultez Extensions OpenAPI 3.x dans API Gateway.

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.0.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. API Gateway n'est pas compatible avec cette fonctionnalité dans OpenAPI 3.x.

Créer une configuration d'API

Créez une configuration d'API à l'aide de votre document OpenAPI 3.x modifié.

Créez la configuration de l'API :
```
gcloud api-gateway api-configs create NEW_CONFIG_ID --api=API_ID --project=PROJECT_ID --openapi-spec=NEW_API_DEFINITION
```
Remplacez les éléments suivants :
- NEW_CONFIG_ID : nouvel ID pour votre configuration d'API.
- API_ID : ID de votre API.
- PROJECT_ID : ID de votre projet Google Cloud .
- NEW_API_DEFINITION : chemin d'accès à votre fichier de spécification OpenAPI 3.x.

Mettre à jour la passerelle

Mettez à jour votre instance de passerelle pour qu'elle fasse référence à la nouvelle configuration d'API à partir de votre document OpenAPI 3.x modifié.

Mettez à jour la passerelle :
```
gcloud api-gateway gateways update GATEWAY_ID --api-config=API_CONFIG --project=PROJECT_ID --location=GATEWAY_LOCATION
```
Remplacez les éléments suivants :
- GATEWAY_ID : ID de votre passerelle.
- API_CONFIG : chemin d'accès complet à la ressource de votre nouvelle configuration d'API, par exemple : projects/PROJECT_ID/locations/global/apis/API_ID/configs/NEW_CONFIG_ID
- PROJECT_ID : ID de votre projet Google Cloud .
- GATEWAY_LOCATION : emplacement de votre passerelle.

Étapes suivantes

En savoir plus sur API Gateway
Explorez la spécification OpenAPI.