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

Limites des fonctionnalités OpenAPI 3.x

Ce document décrit les limites des fonctionnalités pour l'utilisation d'OpenAPI 3.x avec API Gateway.

Pour en savoir plus sur les versions de la spécification OpenAPI compatibles, consultez Présentation d'OpenAPI.

Nouvelles limites d'OpenAPI 3.x

Cette section décrit les limites des nouvelles fonctionnalités d'OpenAPI 3.x.

Serveurs

OpenAPI 3.x est compatible avec plusieurs objets server pour définir des hôtes et des chemins de base. Toutefois, API Gateway s'appuie sur un seul objet serveur, identifié par l'extension x-google-endpoint, pour configurer le service.

Bien que vous puissiez définir plusieurs serveurs, API Gateway ne prend en compte que le serveur contenant l'extension x-google-endpoint et n'autorise qu'un seul serveur de ce type. Pour API Gateway, une URL de serveur n'est pas requise. Vous pouvez donc ne définir aucun serveur ou un serveur avec l'extension x-google-endpoint.

Par exemple, les définitions suivantes sont valides pour API Gateway :

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

La définition suivante n'est pas valide, car elle contient plusieurs extensions x-google-endpoint :

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

La définition suivante est valide pour API Gateway, mais API Gateway ignore l'objet serveur :

servers:
  - url: https://example.com

Serveurs dans plusieurs fichiers

Si vous importez plusieurs fichiers OpenAPI et qu'un fichier contient un serveur avec l'extension x-google-endpoint, tous les fichiers doivent également contenir un serveur défini avec une extension x-google-endpoint identique et un hôte identique dans l'URL du serveur. Le chemin de base peut différer d'un fichier à l'autre.

URL relative

Pour API Gateway, les URL relatives dans l'objet servers sont traitées comme un chemin de base à part entière, car un nom d'hôte n'est pas requis dans la spécification. Cela diffère du comportement OpenAPI standard, qui résout les URL relatives par rapport au serveur hébergeant la définition OpenAPI. Par exemple, API Gateway traite url: /v1 comme un chemin de base.

Les chemins de base doivent commencer par "/". API Gateway rejette les URL qui n'ont pas de schéma ou qui ne commencent pas par "/" pour indiquer un chemin de base.

Extensions non prises en charge

API Gateway n'est pas compatible avec l'extension x-google-allow pour OpenAPI 3.x.

Taille maximale des fichiers

API Gateway applique une limite de taille totale de 10 Mo et une limite de nombre de fichiers de 50 pour les fichiers OpenAPI 3.x importés.

Limites préexistantes

Cette section décrit les limites héritées d'OpenAPI 2.0 qui s'appliquent également à OpenAPI 3.x.

Champs d'application ignorés

Bien qu'API Gateway accepte les documents OpenAPI dont les champs d'application sont définis dans un objet de schéma de sécurité, il ne les vérifie ni ne les applique.

Exigences de sécurité multiples

Exigences concernant les clés API : API Gateway n'est pas compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") si l'un des schémas est une clé API. Toutefois, API Gateway est compatible avec les conjonctions (ET logique), ce qui vous permet d'exiger à la fois une clé API et un jeton OAuth2.
Exigences OAuth2 : API Gateway est compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") pour différents schémas de sécurité OAuth2. API Gateway n'est pas compatible avec les conjonctions (opérateur logique "ET") sauf si l'exigence de sécurité supplémentaire est une clé API.
Sécurité facultative : vous pouvez utiliser une exigence de sécurité vide (- {}) pour rendre la sécurité facultative pour une clé API, mais API Gateway ne prend pas en charge cette option pour OAuth.

Validation de la définition de la sécurité

API Gateway rejettera une spécification OpenAPI 3.x qui utilise une exigence de sécurité sans définition correspondante dans la section securityDefinitions.

Modèles de chemins d'URL

API Gateway n'accepte que les paramètres de modèles de chemin d'URL qui représentent des segments de chemin complets, par exemple /items/{itemId}. API Gateway n'accepte pas les paramètres correspondant à des segments partiels (par exemple, /items/prefix_{id}_suffix) et les rejette.

Paramètres, schémas, corps de requête et types

API Gateway accepte les documents OpenAPI avec différentes définitions de paramètres et de types (par exemple, les paramètres required et les formats de tableau), mais ne les applique pas. API Gateway transfère les requêtes entrantes à votre API, quelles que soient ces définitions.

API Gateway n'accepte que les types primitifs dans les paramètres de requête.

Références à des types externes

API Gateway n'est pas compatible avec les références à des types situés en dehors du document OpenAPI fourni. Par exemple, API Gateway n'autorise pas et rejette un $ref qui pointe vers une URL externe.

Port personnalisé dans l'adresse de l'hôte

API Gateway n'autorise pas les ports personnalisés dans le champ servers.url d'un document OpenAPI.

Limites des alias YAML

Un document OpenAPI envoyé à API Gateway peut comporter jusqu'à 200 nœuds d'alias YAML.