Actualmente, 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 Cloud Endpoints.
Requisitos de seguridad alternativos
Cloud Endpoints no admite requisitos de seguridad alternativos (operador OR lógico). Por ejemplo, no se puede utilizar la siguiente lista de requisitos de seguridad:
security:
- petstore_auth: [...]
- api_key: []
La definición anterior requiere una operación para aceptar peticiones que sigan los requisitos de petstore_auth
o de api_key
.
Sin embargo, Cloud Endpoints sí admite conjunciones de requisitos de seguridad (operador AND lógico). Por ejemplo, la siguiente lista de requisitos de seguridad sí es compatible:
security:
- petstore_auth: [...]
api_key: []
Esta definición requiere una operación para aceptar peticiones que se adecúen simultáneamente los requisitos de petstore_auth
y de api_key
.
Plantillas de ruta de URL
Cloud Endpoints solo admite parámetros de plantilla de ruta de URL que se correspondan con segmentos de ruta completos (delimitados por barras diagonales "/
"). Los parámetros de la plantilla de ruta de URL que se corresponden con segmentos de ruta parciales no se pueden utilizar.
Por ejemplo, se admiten las siguientes plantillas de ruta de URL:
/items/{itemId}
/items/{itemId}/subitems
Sin embargo, las siguientes no están admitidas, por lo que se rechazarán:
/items/overview.{format}
/items/prefix_{id}_suffix
Operaciones en la ruta raíz de URL "/"
Cloud Endpoints acepta documentos de OpenAPI que incluyan operaciones en la ruta raíz "/
". Sin embargo, el proxy de servicios extensible (ESP) rechaza las peticiones en 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 siguientes peticiones de POST /
se rechazarán con el siguiente error:
{
"code": 5,
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "service_control",
"stackEntries": []
}
],
"message": "Method does not exist."
}
Parámetros, esquemas y tipos
Cloud Endpoints ignora la mayoría de las definiciones de parámetros y tipos.
Concretamente, Cloud Endpoints acepta documentos de OpenAPI que incluyan definiciones obligatorias de parámetros y tipos, pero estas no se exigen en las peticiones entrantes. A continuación se detalla una lista parcial con ejemplos de las definiciones que Cloud Endpoints acepta pero no aplica de forma obligatoria:
- 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
Cloud Endpoints no admite referencias a tipos que no formen parte de un documento de OpenAPI. Por ejemplo, Cloud Endpoints rechaza documentos de OpenAPI que incluyan lo siguiente:
parameters:
- name: user
description: User details
in: body
schema:
$ref: "https://example.com/mytype.json"
Errores conocidos
Rechazo de documentos de OpenAPI
Cuando se despliegan documentos de OpenAPI mediante gcloud endpoints services deploy
, Cloud Endpoints rechaza aquellos 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
Limitaciones de la clave de API
Al especificar una clave de API en el objeto de definiciones de seguridad del documento de OpenAPI, Cloud Endpoints exige lo siguiente:
- El campo
name
debe serkey
. - El campo
in
debe serquery
.
Por ejemplo:
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "key",
"in": "query"
}
Cuando se despliegan documentos de OpenAPI con otros tipos de definiciones de seguridad de la clave de API, es posible que Cloud Endpoints los acepte y muestre una advertencia. Sin embargo, las definiciones de seguridad de la clave API se ignoran en las peticiones entrantes.