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: []

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, la version bêta d'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."
}

Paramètres, schémas et types

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

Endpoints accepte 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 vers votre API. Vous trouverez ci-dessous une liste non exhaustive d'exemples de définitions que ESP accepte, mais 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 relatives aux clés API

Lorsque vous spécifiez une clé API dans l'objet de définitions de sécurité de votre document OpenAPI, Endpoints applique les exigences suivantes :

  • Le champ name doit être key.
  • Le champ in doit être query.

Exemple :

"securityDefinitions": {
  "api_key": {
    "type": "apiKey",
    "name": "key",
    "in": "query"
  }

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.