Limites des fonctionnalités OpenAPI

OpenAPI | gRPC

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

Les sections ci-dessous décrivent les limites des fonctionnalités OpenAPI sur 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.

Exigences de sécurité contenant une clé API

ESP n'est pas compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") lorsque l'un des schémas de sécurité est une clé d'API. Par exemple, ESP n'est pas compatible 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 est compatible 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 est compatible 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é

Le proxy ESP ne vérifie pas que toutes les exigences de sécurité (que ce soit 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 toutes les clés de sécurité utilisées par votre API et ses méthodes sont définies sous les définitions de sécurité du 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."
}

Importer un fichier

Cloud Endpoints n'accepte pas les paramètres type: file pour l'importation de fichiers. Utilisez type: string à la place.

Par exemple, l'extrait 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.

Alors que les éléments suivants sont autorisés avec type: string:

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 ignore la plupart des définitions de paramètres et de types.

Cloud Endpoints accepte les documents OpenAPI qui incluent les définitions de paramètres et de types requis, mais ESP n'applique pas ces définitions et transfère les requêtes entrantes à l'API. Vous trouverez ci-dessous une liste partielle d'exemples de définitions non appliquées par ESP:

• 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 liées aux alias YAML

Les points de terminaison acceptent jusqu'à 200 nœuds d'alias YAML dans un document OpenAPI. S'il existe plus de 200 alias YAML dans un document OpenAPI, nous vous recommandons de déréférencer les alias dans la mesure du possible afin de respecter cette 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.

Le portail Cloud Endpoints n'affiche pas les types de composition

Bien que Endpoints accepte les documents OpenAPI avec des types de composition, c'est-à-dire avec allOf dans la définition, le portail Endpoints ne génère pas de documentation sur les types de composition.