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
eskey
y elin
esquery
- El
name
esapi_key
y elin
esquery
- El
name
esx-api-key
y elin
esheader
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.