Limites des fonctionnalités OpenAPI

Cloud Endpoints n'est compatible qu'avec la version 2 de la spécification OpenAPI.

Les sections suivantes décrivent les limites des fonctionnalités OpenAPI sur Cloud Endpoints.

Champs d'application ignorés

Bien que Endpoints soit compatible avec les documents OpenAPI dont les champs d'application sont définis dans un objet de schéma de sécurité, lorsqu'une requête est envoyée à votre API, ni les frameworks ESP (Extensible Service Proxy), ni les frameworks Cloud Endpoints ne vérifient les champs d'application définis.

Exigences de sécurité multiples

Vous pouvez spécifier plusieurs exigences de sécurité dans votre document OpenAPI. Cette section décrit les schémas de sécurité compatibles avec ESP et ESPv2.

Exigences de sécurité contenant une clé API

ESP et ESPv2 ne sont pas compatibles avec la sécurité alternative (opérateur logique OU). des exigences lorsque l'un des schémas de sécurité est une clé API. Par exemple : ESP et ESPv2 ne sont pas compatibles avec les exigences de sécurité suivantes:

security:
- petstore_auth: []
- api_key: []

Cette définition nécessite une opération pour que les requêtes qui répondent aux exigences petstore_auth et api_key soient acceptées.

Notez cependant que ESP et ESPv2 sont compatibles avec les combinaisons d'exigences de sécurité (opérateur logique "ET"), de sorte que vous pouvez exiger à la fois une clé API et une authentification OAuth2. Par exemple, la liste des exigences de sécurité suivante est acceptée :

security:
- petstore_auth: []
  api_key: []

Cette définition nécessite une opération pour que les requêtes qui répondent simultanément aux exigences petstore_auth et api_key soient acceptées.

Exigences de sécurité pour OAuth2

ESP et ESPv2 sont compatibles avec les exigences de sécurité avec alternatives (opérateur logique OU), mais uniquement pour les schémas de sécurité d'authentification OAuth2. Par exemple, la liste des exigences de sécurité suivante est acceptée :

security:
  - firebase1: []
  - firebase2: []

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

ESP et ESPv2 ne valident pas que toutes les exigences de sécurité (au niveau de l'API ou de la méthode) sont également présentes dans la section securityDefinitions. Par conséquent, si la spécification de l'API utilise un schéma de sécurité non défini, des requêtes non authentifiées peuvent passer par l'API, au niveau où la clé de sécurité non définie est configurée. Assurez-vous que tous les clés de sécurité utilisées par votre API et ses méthodes sont définies dans le dans votre document OpenAPI.

Modèles de chemins d'URL

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 des barres obliques /). Les paramètres de modèles de chemin d'URL qui correspondent à des segments de chemin partiels ne sont pas acceptés.

Par exemple, les modèles de chemins d'URL suivants sont compatibles :

  • /items/{itemId}
  • /items/{itemId}/subitems

Les modèles de chemins d'URL suivants ne sont pas compatibles et seront refusés :

  • /items/overview.{format}
  • /items/prefix_{id}_suffix

Opérations sur le chemin d'URL racine /

Endpoints accepte les documents OpenAPI qui incluent des opérations sur le chemin d'URL racine /. Cependant, les requêtes effectuées sur le chemin racine sont refusées par l'ESP. Notez que cette limitation ne s'applique qu'à l'ESP. ESPv2 est compatible avec le chemin d'accès racine /.

Par exemple, l'extrait de document OpenAPI suivant est accepté :

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

Les requêtes ultérieures pour POST / sont rejetées avec l'erreur suivante :

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

Importation de fichier

Endpoints n'accepte pas les type: file pour l'importation de fichiers , vous devez utiliser type: string à la place.

Par exemple, l'extrait de code type: file suivant n'est pas autorisé :

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

En revanche, les éléments suivants avec type: string sont autorisés :

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

Paramètres, schémas et types

ESP et ESPv2 ignorent la plupart des définitions de paramètres et de types.

Cloud Endpoints accepte les documents OpenAPI qui incluent le code de paramètres et de types, mais ESP et ESPv2 ne les appliquent pas et transmet les requêtes entrantes à votre API. Vous trouverez ci-dessous une liste non exhaustive d'exemples de définitions que ESP et ESPv2 n'appliquent pas :

  • Paramètres de données de formulaire, par exemple :
    parameters:
- name: avatar
  in: formData
  description: "The avatar of the user"
  type: string
  • Paramètres obligatoires, par exemple :
    parameters:
- name: message
  in: query
  description: "Message to send"
  required: true
  type: string
  • Formats de collection de tableaux, par exemple :
    parameters:
- name: items
  in: query
  description: "List of item IDs"
  required: true
  type: array
  items:
    type: string
  collectionFormat: tsv
  • Composition de types, par exemple :
    definitions:
  base:
    properties:
      message:
        type: string
  extended:
    description: "Extends the base type"
    allOf:
    - $ref: "#/definitions/base"
    - type: object
      properties:
        extension:
          type: string
  • Différents objets de réponses par code d'état, par exemple :
    responses:
  200:
    description: "Echo"
    schema:
      $ref: "#/definitions/EchoResponse"
  400:
    description: "Error"
    schema:
      type: string

Références à des types externes

Endpoints n'est pas compatible avec les références à des types situés en dehors du document OpenAPI. Par exemple, Endpoints n'accepte pas les documents OpenAPI qui incluent des références telles que celle-ci :

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

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

Endpoints n'autorise pas les ports personnalisés dans le champ host d'un document OpenAPI. Par exemple, Endpoints n'accepte pas les documents OpenAPI tels que :

swagger: 2.0
host: example.com:8080
schemes:
- http

Limites des alias YAML

Les points de terminaison peuvent prendre en charge jusqu'à 200 nœuds d'alias YAML dans un document OpenAPI. S'il existe plus de 200 alias YAML dans une OpenAPI , nous vous recommandons de déréférencer dans la mesure du possible les alias limite.

Bugs connus

Documents OpenAPI rejetés

Lorsque vous déployez un document OpenAPI à l'aide de gcloud endpoints services deploy, Endpoints rejette les documents OpenAPI qui incluent :

  • Paramètres de corps de tableau, par exemple : 
    parameters:
- name: message
  description: "Message to echo"
  in: body
  schema:
    type: array
    items:
      type: string
  • Chemins se terminant par des barres obliques, par exemple : 
    paths:
  "/echo/":
    post:
      description: "Echo back a given message."

    Pour résoudre ce problème, supprimez la barre oblique finale de /echo/ :

    paths:
  "/echo":
    post:
      description: "Echo back a given message."

Limites applicables à la définition de clé API

Lorsque vous spécifiez une clé API dans l'objet de définitions de sécurité de votre document OpenAPI, Endpoints requiert l'un des schémas suivants :

  • name est défini sur key et in est défini sur query.
  • name est défini sur api_key et in est défini sur query.
  • name est défini sur x-api-key et in est défini sur header.

Exemple :

"securityDefinitions": {
  "api_key_0": {
        "type": "apiKey",
        "name": "key",
        "in": "query"
    },
  "api_key_1": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
    }
  "api_key_2": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
    },
}

Lorsque vous déployez un document OpenAPI avec d'autres types de définitions de sécurité pour les clés API, Endpoints peut les accepter et générer un avertissement. Toutefois, ces définitions sont ignorées dans les requêtes entrantes.