Limitaciones de las características de OpenAPI

OpenAPI  |  gRPC

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

En las siguientes secciones, 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), el proxy de servicio extensible V2 (ESPv2) 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 admiten ESP y ESPv2.

Requisitos de seguridad que contienen una clave de API

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

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 y el ESPv2 admiten 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 y el ESPv2 admiten 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 la definición de seguridad

ESP y ESPv2 no validan que todos los requisitos de seguridad (ya sea a nivel de API o del método) también estén presentes en la sección 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 claves de seguridad que usa tu API y sus métodos estén definidas en las definiciones de seguridad de 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

Los extremos no aceptan type: file para los parámetros de carga de archivos, por lo que se debe usar 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.

Mientras que 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 los documentos de OpenAPI que incluyen definiciones obligatorias de parámetros y tipos, pero ESP y ESPv2 no aplican 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 y el ESPv2 no aplican:

• 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

Endpoints puede admitir hasta 200 nodos de alias YAML en un documento de OpenAPI. Si hay más de 200 alias de YAML en un documento de OpenAPI, te recomendamos que desreferencias los alias siempre que sea posible para cumplir con este 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.