Ce document décrit les limites des fonctionnalités pour l'utilisation d'OpenAPI 3.x avec Endpoints.
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 d'OpenAPI qui sont nouvelles avec la compatibilité 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, Cloud Endpoints n'utilise qu'un seul objet serveur pour configurer le nom d'hôte et le chemin de base, identifiés par l'extension x-google-endpoint.
Bien que vous puissiez définir plusieurs serveurs dans votre spécification OpenAPI, Cloud Endpoints n'utilise que le serveur avec l'extension x-google-endpoint. Vous ne pouvez définir l'extension x-google-endpoint que sur un seul serveur.
Pour Cloud Endpoints, un nom d'hôte est requis. Par conséquent, un seul serveur doit disposer de l'extension x-google-endpoint.
Par exemple, les définitions de serveur suivantes sont valides pour Cloud Endpoints :
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
- url: https://example.com
La définition de serveur suivante n'est pas valide pour Endpoints :
servers:
- url: https://my-api-1.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
- url: https://my-api-2.endpoints.my-project-id.cloud.goog
x-google-endpoint: {}
La définition suivante est également invalide pour Cloud Endpoints :
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Serveurs dans plusieurs fichiers
Si vous importez plusieurs fichiers OpenAPI, tous les fichiers doivent respecter les limites de la section servers. Si un fichier contient un serveur avec l'extension x-google-endpoint, tous les fichiers doivent définir un serveur avec l'extension x-google-endpoint.
De plus, tous les serveurs avec l'extension x-google-endpoint doivent utiliser un hôte identique dans l'URL du serveur, et la configuration x-google-endpoint doit être identique dans tous les fichiers. Le chemin de base de l'URL du serveur peut être différent.
URL relative
Cloud Endpoints nécessite un nom d'hôte et n'est donc pas compatible avec les URL relatives.
Extensions non prises en charge
OpenAPI 3.x n'est pas compatible avec l'extension x-google-allow.
Limites préexistantes
Cette section décrit les limites qui existaient dans OpenAPI 2.0 et qui continuent de s'appliquer à OpenAPI 3.x.
Champs d'application ignorés
Bien que vous puissiez définir des champs d'application dans un objet de schéma de sécurité, ESP ou les frameworks Cloud Endpoints ne les vérifient pas.
Exigences de sécurité multiples
Vous pouvez spécifier plusieurs exigences de sécurité dans votre document OpenAPI.
Exigences de sécurité avec une clé API : Cloud Endpoints n'est pas compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") lorsque l'un des schémas est une clé API. Cloud Endpoints est compatible avec les combinaisons (opérateur logique "ET"), de sorte que vous pouvez exiger à la fois une clé API et une authentification OAuth2.
Exigences de sécurité pour OAuth2 : Cloud Endpoints est compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") pour différents schémas d'authentification OAuth2. Cloud Endpoints n'est pas compatible avec les conjonctions (opérateur logique "ET") sauf si l'exigence de sécurité supplémentaire est une clé API.
Exigences de sécurité facultatives : OpenAPI 3 est compatible avec la sécurité facultative en incluant une exigence vide (
{}). La clé API est compatible avec cette fonctionnalité, mais pas OAuth.
Validation de la définition de la sécurité
Pour OpenAPI 3.x, l'utilisation d'un schéma de sécurité non défini entraîne une erreur, et Cloud Endpoints rejette la spécification. C'est une différence par rapport à OpenAPI 2.0, où cela ne produisait qu'un avertissement.
Modèles de chemins d'URL
Cloud Endpoints n'accepte que les paramètres de modèles de chemin d'URL qui correspondent à des segments de chemin complets (délimités par /). Il n'accepte pas les paramètres pour les segments de chemin partiels.
Par exemple, Cloud Endpoints est compatible avec /items/{itemId}, mais pas avec /items/overview.{format}.
Opérations sur le chemin d'URL racine /
Bien que le document OpenAPI accepte les opérations sur le chemin racine /, Extensible Service Proxy refuse les requêtes adressées au chemin racine. Cette limitation ne s'applique pas à ESPv2, qui est compatible avec le chemin d'accès racine.
Paramètres, schémas, corps de requête et types
Extensible Service Proxy et ESP ignorent la plupart des définitions de paramètres, de schémas, de corps de requête et de types. Extensible Service Proxy et ESP n'appliquent pas les paramètres et les définitions de type obligatoires, et ils transfèrent les requêtes à votre API.
Extensible Service Proxy et ESP n'acceptent que les types primitifs dans les paramètres de requête.
Références à des types externes
Cloud Endpoints n'est pas compatible avec les références à des types situés en dehors du document OpenAPI. Par exemple, vous ne pouvez pas utiliser $ref vers une URL externe.
Port personnalisé dans l'adresse de l'hôte de service
Vous ne pouvez pas utiliser de ports personnalisés dans le url d'un objet servers.
Limites des alias YAML
Un document OpenAPI peut contenir jusqu'à 200 nœuds d'alias YAML.
Corps de la requête non répétitif
Vous ne pouvez définir qu'un seul requestBody par opération, et il doit être de type non répétitif.