Limitaciones de las funciones de OpenAPI

Actualmente, Cloud Endpoints solo acepta la versión 2 de la especificación OpenAPI.

En las siguientes secciones se describen las limitaciones de las funciones de OpenAPI en Cloud Endpoints.

Requisitos de seguridad alternativos

Cloud Endpoints no admite requisitos de seguridad alternativos (operador OR lógico). Por ejemplo, no se puede utilizar la siguiente lista de requisitos de seguridad:

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

La definición anterior requiere una operación para aceptar peticiones que sigan los requisitos de petstore_auth o de api_key.

Sin embargo, Cloud Endpoints sí admite conjunciones de requisitos de seguridad (operador AND lógico). Por ejemplo, la siguiente lista de requisitos de seguridad sí es compatible:

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

Esta definición requiere una operación para aceptar peticiones que se adecúen simultáneamente los requisitos de petstore_auth y de api_key.

Plantillas de ruta de URL

Cloud Endpoints solo admite parámetros de plantilla de ruta de URL que se correspondan con segmentos de ruta completos (delimitados por barras diagonales "/"). Los parámetros de la plantilla de ruta de URL que se corresponden con segmentos de ruta parciales no se pueden utilizar.

Por ejemplo, se admiten las siguientes plantillas de ruta de URL:

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

Sin embargo, las siguientes no están admitidas, por lo que se rechazarán:

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

Operaciones en la ruta raíz de URL "/"

Cloud Endpoints acepta documentos de OpenAPI que incluyan operaciones en la ruta raíz "/". Sin embargo, el proxy de servicios extensible (ESP) rechaza las peticiones en la ruta raíz.

Por ejemplo, se puede utilizar el siguiente fragmento de documento de OpenAPI:

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

Sin embargo, las siguientes peticiones de POST / se rechazarán con el siguiente error:

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

Parámetros, esquemas y tipos

Cloud Endpoints ignora la mayoría de las definiciones de parámetros y tipos.

Concretamente, Cloud Endpoints acepta documentos de OpenAPI que incluyan definiciones obligatorias de parámetros y tipos, pero estas no se exigen en las peticiones entrantes. A continuación se detalla una lista parcial con ejemplos de las definiciones que Cloud Endpoints acepta pero no aplica de forma obligatoria:

  • Parámetros de datos de formulario, como:
    parameters:
    - name: avatar
      in: formData
      description: "The avatar of the user"
      type: string
  • Parámetros obligatorios, como:
    parameters:
    - name: message
      in: query
      description: "Message to send"
      required: true
      type: string
  • Formatos de colección de matriz, como:
    parameters:
    - name: items
      in: query
      description: "List of item IDs"
      required: true
      type: array
      items:
        type: string
      collectionFormat: tsv
  • Composición de tipos, como:
    definitions:
      base:
        properties:
          message:
            type: string
      extended:
        description: "Extends the base type"
        allOf:
        - $ref: "#/definitions/base"
        - type: object
          properties:
            extension:
              type: string
  • Objetos de respuesta distintos por cada código de estado, como:
    responses:
      200:
        description: "Echo"
        schema:
          $ref: "#/definitions/EchoResponse"
      400:
        description: "Error"
        schema:
          type: string

Referencias de tipos externos

Cloud Endpoints no admite referencias a tipos que no formen parte de un documento de OpenAPI. Por ejemplo, Cloud Endpoints rechaza documentos de OpenAPI que incluyan lo siguiente:

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

Errores conocidos

Rechazo de documentos de OpenAPI

Cuando se despliegan documentos de OpenAPI mediante gcloud endpoints services deploy, Cloud Endpoints rechaza aquellos que incluyen lo siguiente:

  • Parámetros del contenido de la matriz, como:
    parameters:
    - name: message
      description: "Message to echo"
      in: body
      schema:
        type: array
        items:
          type: string

Limitaciones de la clave de API

Al especificar una clave de API en el objeto de definiciones de seguridad del documento de OpenAPI, Cloud Endpoints exige lo siguiente:

  • El campo name debe ser key.
  • El campo in debe ser query.

Por ejemplo:

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

Cuando se despliegan documentos de OpenAPI con otros tipos de definiciones de seguridad de la clave de API, es posible que Cloud Endpoints los acepte y muestre una advertencia. Sin embargo, las definiciones de seguridad de la clave API se ignoran en las peticiones entrantes.