Limites des fonctionnalités OpenAPI

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 sécurité

ESP ne vérifie 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 API utilise un schéma de sécurité non défini, les requêtes non authentifiées peuvent provenir de 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 dans les définitions de sécurité de 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

Cloud Endpoints n'accepte pas type: file pour les paramètres d'importation de fichier. type: string doit être utilisé à 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.

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.

Les points de terminaison acceptent les documents OpenAPI qui incluent des définitions de paramètres et de types obligatoires, mais ESP n'applique pas ces définitions et transfère les requêtes entrantes à votre API. La liste suivante fournit des exemples de définitions que ESP n'applique 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

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.