Limitaciones de las características de OpenAPI

OpenAPI   |  gRPC

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

En las secciones siguientes, se describen las limitaciones de las características de OpenAPI en Endpoints.

Alcances ignorados

Aunque Endpoints acepta documentos de OpenAPI con alcances definidos en un objeto de esquema de seguridad, cuando se envía una solicitud a tu API, ni el proxy de servicio extensible (ESP) ni Cloud Endpoints Frameworks verifican los alcances 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 admite el ESP.

Requisitos de seguridad que contienen una clave de API

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

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

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

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

security:
- petstore_auth: []
  api_key: []

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

Requisitos de seguridad para OAuth2

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

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

Validación de las definiciones de seguridad

El ESP no valida que todos los requisitos de seguridad (ya sea (nivel de API o método), también están presentes en el securityDefinitions. Como resultado, si la especificación de la API usa un esquema de seguridad no definido, es posible que las solicitudes no autenticadas lleguen a través de la API, en el nivel en el que se configura la clave de seguridad no definida. Asegúrate de que todas las llaves de seguridad que usa tu API y sus métodos se definen bajo el definiciones en tu documento de OpenAPI.

Plantillas de ruta de URL

Endpoints solo admite parámetros de plantilla de ruta de aceso de URL que corresponden a segmentos de ruta de acceso completos (delimitados por barras diagonales /). Los parámetros de plantilla de ruta de URL que corresponden a segmentos de ruta parciales no son compatibles.

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

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

Las plantillas de ruta de URL siguientes no son compatibles y se rechazarán:

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

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

Endpoints acepta documentos de OpenAPI que incluyen operaciones en la ruta raíz /. Sin embargo, el ESP rechaza las solicitudes en la ruta de acceso raíz. Ten en cuenta que esta limitación es solo para el ESP, ESPv2 admite la ruta de acceso raíz /.

Por ejemplo, se acepta el fragmento de documento de OpenAPI siguiente:

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

Sin embargo, las solicitudes posteriores de POST / se rechazan con el error siguiente:

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

Carga de archivo

Endpoints no acepta las type: file para la carga de archivos parámetros, se debe usar type: string en su lugar.

Por ejemplo, no se permite el siguiente fragmento de 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.

Por otro lado, 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

El ESP ignora la mayoría de las definiciones de parámetros y tipos.

Endpoints acepta los documentos de OpenAPI que incluyen definiciones obligatorias de parámetros y tipos, pero el ESP no aplica estas definiciones ni reenvía las solicitudes entrantes a tu API. La siguiente es una lista parcial que proporciona ejemplos de las definiciones que el ESP no aplica:

• Parámetros de datos de formularios, por ejemplo:

  parameters:
  - name: avatar
    in: formData
    description: "The avatar of the user"
    type: string

• Parámetros obligatorios, por ejemplo:

  parameters:
  - name: message
    in: query
    description: "Message to send"
    required: true
    type: string

• Formatos de colección de arreglos, por ejemplo:

  parameters:
  - name: items
    in: query
    description: "List of item IDs"
    required: true
    type: array
    items:
      type: string
    collectionFormat: tsv

• Composición de tipo, por ejemplo:

  definitions:
    base:
      properties:
        message:
          type: string
    extended:
      description: "Extends the base type"
      allOf:
      - $ref: "#/definitions/base"
      - type: object
        properties:
          extension:
            type: string

• Diferentes objetos de respuesta por código de estado, por ejemplo:

  responses:
    200:
      description: "Echo"
      schema:
        $ref: "#/definitions/EchoResponse"
    400:
      description: "Error"
      schema:
        type: string

Referencias a tipos externos

Endpoints no admite referencias a tipos fuera de un documento de OpenAPI. Por ejemplo, Endpoints rechaza los 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 una dirección de host de 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 extremos pueden admitir hasta 200 nodos de alias YAML en un Documento de OpenAPI. Si hay más de 200 alias YAML en una OpenAPI documento, recomendamos anular la referencia de los alias siempre que sea posible para cumplir con límite.

Errores conocidos

Documentos de OpenAPI rechazados

Cuando implementas tu documento de OpenAPI con gcloud endpoints services deploy, Endpoints rechaza los documentos de OpenAPI que incluyen lo siguiente:

• Parámetros del cuerpo de un arreglo, por ejemplo:

  parameters:
  - name: message
    description: "Message to echo"
    in: body
    schema:
      type: array
      items:
        type: string

• Rutas de acceso con barras finales, por ejemplo:

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

  Para solucionar este problema, quita la barra diagonal final de /echo/ de la siguiente manera:

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

Limitaciones de la definición de la clave de API

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

• 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 implementas un documento de OpenAPI con otros tipos de definiciones de seguridad de la clave de API, es posible que Endpoints los acepte y envíe una advertencia. Sin embargo, las definiciones de seguridad de la clave de API se ignoran en las solicitudes entrantes.

El portal de Cloud Endpoints no procesa tipos de composición

Aunque Endpoints acepta documentos de OpenAPI con tipos de composición, es decir, tipos con allOf en la definición, el portal de Endpoints no genera documentación para los tipos de composición.