Limitaciones de las características de OpenAPI

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

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, la versión Beta de 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."
}

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

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 requiere uno de los siguientes esquemas:

  • name es key y in es query.
  • name es api_key y in es query.
  • name es x-api-key y 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.