Limitaciones de las funciones de OpenAPI

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 Endpoints.

Permisos ignorados

Aunque Endpoints acepta documentos de OpenAPI que tienen ámbitos definidos en un objeto de esquema de seguridad, cuando se envía una solicitud a tu API, ni el proxy de servicios extensible (ESP), ni el proxy de servicios extensible V2 (ESPv2), ni Cloud Endpoints Frameworks comprueban los ámbitos definidos.

Varios requisitos de seguridad

Puedes especificar más de un requisito de seguridad en tu documento de OpenAPI. En esta sección se describen los esquemas de seguridad que admiten ESP y ESPv2.

Requisitos de seguridad que contienen una clave de API

ESP y ESPv2 no admiten requisitos de seguridad alternativos (OR lógico) cuando uno de los esquemas de seguridad es una clave de API. Por ejemplo, ESP y ESPv2 no admiten la siguiente lista de requisitos de seguridad:

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

Esta definición requiere que una operación acepte solicitudes que cumplan los petstore_auth requisitos o los api_key requisitos.

Sin embargo, ten en cuenta que ESP y ESPv2 admiten conjunciones de requisitos de seguridad (AND lógico), por lo que puedes requerir tanto una clave de API como la autenticación OAuth2. Por ejemplo, se admite la siguiente lista de requisitos de seguridad:

security:
- petstore_auth: []
  api_key: []

Esta definición requiere que una operación acepte solicitudes que cumplan simultáneamente los petstore_auth requisitos y los api_key requisitos.

Requisitos de seguridad de OAuth2

ESP y ESPv2 admiten requisitos de seguridad alternativos (OR lógico), pero solo para esquemas de seguridad de autenticación OAuth2. Por ejemplo, se admite la siguiente lista de requisitos de seguridad:

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

Validación de la definición de seguridad

ESP y ESPv2 no validan que todos los requisitos de seguridad (ya sea a nivel de API o de método) también estén presentes en la sección securityDefinitions. Por lo tanto, si la especificación de la API usa un esquema de seguridad indefinido, es posible que las solicitudes no autenticadas lleguen a la API en el nivel en el que se configura la clave de seguridad indefinida. Asegúrate de que todas las claves de seguridad que usen tu API y sus métodos estén definidas en las definiciones de seguridad de tu documento de OpenAPI.

Creación de plantillas de ruta de URL

Los endpoints solo admiten parámetros de plantilla de ruta de URL que correspondan a segmentos de ruta completos (delimitados por barras /). No se admiten los parámetros de plantilla de ruta de URL que correspondan a segmentos de ruta parciales.

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

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

No se admiten las siguientes plantillas de ruta de URL y se rechazarán:

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

Operaciones en la ruta raíz de la URL /

Endpoints acepta documentos de OpenAPI que incluyen operaciones en la ruta raíz /. Sin embargo, ESP rechaza las solicitudes de la ruta raíz. Ten en cuenta que esta limitación solo se aplica a ESP. ESPv2 admite 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 solicitudes posteriores de POST / se rechazan con el siguiente error:

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

Subir archivo

Endpoints no acepta type: file para los parámetros de subida de archivos. En su lugar, debe usarse type: string.

Por ejemplo, no se permite el siguiente fragmento type: file:

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

En cambio, se permite lo siguiente con 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.

Parámetros, esquemas y tipos

ESP y ESPv2 ignoran la mayoría de las definiciones de parámetros y tipos.

Endpoints acepta documentos de OpenAPI que incluyen definiciones de parámetros y tipos obligatorios, pero ESP y ESPv2 no aplican estas definiciones y reenvían las solicitudes entrantes a tu API. A continuación, se muestra una lista parcial con ejemplos de las definiciones que ESP y ESPv2 no aplican:

  • 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

Endpoints no admite referencias a tipos que no estén en un documento de OpenAPI. Por ejemplo, Endpoints rechaza documentos de OpenAPI que incluyen lo siguiente:

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

Puerto personalizado en la dirección del host del servicio

Endpoints no permite puertos personalizados en el campo host de un documento de OpenAPI. Por ejemplo, Endpoints rechaza documentos de OpenAPI como los siguientes:

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

Limitaciones de los alias de YAML

Los endpoints pueden admitir hasta 200 nodos de alias YAML en un documento de OpenAPI. Si hay más de 200 alias YAML en un documento de OpenAPI, te recomendamos que desreferencies los alias siempre que sea posible para cumplir este límite.

Errores conocidos

Rechazo de documentos de OpenAPI

Cuando despliega su documento OpenAPI mediante gcloud endpoints services deploy, Endpoints rechaza los documentos OpenAPI 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
  • Rutas con barras inclinadas al final, por ejemplo: 
    paths:
  "/echo/":
    post:
      description: "Echo back a given message."

    Para solucionar este problema, elimine la barra inclinada final de /echo/:

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

Limitaciones de la definición de claves de API

Cuando especifiques una clave de API en el objeto de definiciones de seguridad de tu documento de OpenAPI, Endpoints requerirá uno de los siguientes esquemas:

  • El name es key y el in es query
  • El name es api_key y el in es query
  • El name es x-api-key y el in es header

Por ejemplo:

"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"
    },
}

Cuando despliega un documento de OpenAPI con otros tipos de definiciones de seguridad de claves de API, Endpoints puede aceptarlos y mostrar una advertencia. Sin embargo, las definiciones de seguridad de la clave API se ignoran en las peticiones entrantes.