Ce document décrit les limites des fonctionnalités liées à l'utilisation d'OpenAPI 3.x avec Endpoints.
Pour en savoir plus sur les versions de spécification OpenAPI compatibles, consultez la présentation d'OpenAPI.
Nouvelles limites d'OpenAPI 3.x
Cette section décrit les limites d'OpenAPI qui sont nouvelles avec la compatibilité avec 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 n'est pas non plus valide pour Cloud Endpoints :
servers:
- url: https://my-api.endpoints.my-project-id.cloud.goog
Serveurs sur 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 une 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 dans l'URL du serveur peut être différent.
URL relative
Cloud Endpoints nécessite un nom d'hôte. Par conséquent, il n'est 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 combinaisons (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 sécurité
Pour OpenAPI 3.x, l'utilisation d'un schéma de sécurité non défini génère une erreur, et Cloud Endpoints rejette la spécification. Il s'agit d'un changement par rapport à OpenAPI 2.0, où cela ne produisait qu'un avertissement.
Modèles de chemins d'URL
Cloud Endpoints n'est compatible qu'avec les paramètres de modèles de chemins d'URL qui correspondent à des segments de chemins complets (délimités par /). Cloud Endpoints n'est pas compatible avec les paramètres pour les segments de chemins 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 d'URL racine /, Extensible Service Proxy rejette les requêtes adressées au chemin d'URL racine. Cette limite ne s'applique pas à ESPv2, qui est compatible avec le chemin d'URL 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 requis ni les définitions de types, et ils transfèrent les requêtes à votre API.
Extensible Service Proxy et ESP ne sont compatibles qu'avec 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 de $ref pour une URL externe.
Port personnalisé dans l'adresse de l'hôte de service
Vous ne pouvez pas utiliser de ports personnalisés dans l'url d'un objet servers.
Limites des alias YAML
Un document OpenAPI peut contenir un maximum de 200 nœuds d'alias YAML.
Corps de requête non répétitif
Vous ne pouvez définir qu'un seul requestBody par opération, et il doit être d'un type non répétitif.