No momento, o Cloud Endpoints aceita somente versão 2 da Especificação OpenAPI.
Nas seções abaixo, descrevemos as limitações dos recursos da OpenAPI no Endpoints.
Escopos ignorados
Ainda que o Endpoints aceite documentos da OpenAPI que tenham escopos definidos em um objeto de esquema de segurança, quando uma solicitação é enviada à API, o Extensible Service Proxy (ESP) e o Endpoints Frameworks não verificam os escopos definidos.
Vários requisitos de segurança
É possível especificar mais de um requisito de segurança no documento do OpenAPI. Nesta seção, descrevemos os esquemas de segurança compatíveis com o ESP.
Requisitos de segurança que contêm uma chave de API
O ESP não aceita requisitos de segurança alternativa (OR lógico) quando um dos esquemas de segurança é uma chave de API. Por exemplo, o ESP não aceita a seguinte lista de requisitos de segurança:
security:
- petstore_auth: []
- api_key: []
Essa definição requer uma operação para aceitar solicitações que sigam os requisitos petstore_auth
ou os requisitos api_key
.
No entanto, o ESP aceita conjunções de requisitos de segurança (AND lógico) para que você exija uma chave de API e a autenticação do OAuth2. Por exemplo, a lista de requisitos de segurança a seguir é aceita:
security:
- petstore_auth: []
api_key: []
Essa definição requer uma operação para aceitar solicitações que atendam aos requisitos petstore_auth
e api_key
simultaneamente.
Requisitos de segurança para OAuth2
O ESP aceita requisitos de segurança alternativos (OR lógico), mas apenas nos esquemas de autenticação OAuth2. Por exemplo, a seguinte lista de requisitos de segurança é aceita:
security:
- firebase1: []
- firebase2: []
Modelos do caminho do URL
O Endpoints aceita apenas parâmetros de modelo de caminho do URL que correspondem a segmentos de caminho inteiros (delimitados por barras /
). Os parâmetros de modelo de caminho de URL que correspondem a segmentos de caminho parciais não são aceitos.
Por exemplo, os modelos de caminho do URL a seguir são aceitos:
/items/{itemId}
/items/{itemId}/subitems
Os seguintes modelos de caminho de URL não são aceitos e serão rejeitados:
/items/overview.{format}
/items/prefix_{id}_suffix
Operações no caminho raiz do URL /
O Endpoints aceita documentos da OpenAPI que incluem operações no caminho raiz /
. No entanto, as solicitações no caminho raiz são rejeitadas pelo ESP. Observe que essa limitação é apenas para ESP,
ESPv2 é compatível com o caminho raiz /
.
Por exemplo, o seguinte snippet de documento OpenAPI é aceito:
paths:
/:
post:
operationId: "root"
responses:
200:
description: "Success"
schema:
type: string
Mas as solicitações subsequentes de POST /
são rejeitadas com este erro:
{
"code": 5,
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "service_control",
"stackEntries": []
}
],
"message": "Method does not exist."
}
Parâmetros, esquemas e tipos
O ESP ignora a maioria das definições de parâmetro e tipo.
O Endpoints aceita documentos OpenAPI que incluam parâmetros e definições de tipo obrigatórias, mas o ESP não restringe essas definições e encaminha as solicitações à sua API. Veja a seguir uma lista com alguns exemplos de definições que o ESP não restringe:
- Parâmetros dos dados do formulário, como:
parameters: - name: avatar in: formData description: "The avatar of the user" type: string
- Parâmetros necessários, como:
parameters: - name: message in: query description: "Message to send" required: true type: string
- Formatos de coleção de matrizes, como:
parameters: - name: items in: query description: "List of item IDs" required: true type: array items: type: string collectionFormat: tsv
- Composição do tipo, 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 resposta diferentes por código de status, como:
responses: 200: description: "Echo" schema: $ref: "#/definitions/EchoResponse" 400: description: "Error" schema: type: string
Referências de tipo externo
O Endpoints não aceita referências a tipos fora de um documento da OpenAPI. Por exemplo, o Endpoints rejeita documentos da OpenAPI que incluem:
parameters:
- name: user
description: User details
in: body
schema:
$ref: "https://example.com/mytype.json"
Porta personalizada no endereço do host de serviço
O Endpoints não permite portas personalizadas no campo host
de um documento da OpenAPI. Por exemplo, o Endpoints rejeita documentos da OpenAPI, como:
swagger: 2.0
host: example.com:8080
schemes:
- http
Bugs conhecidos
Documentos da OpenAPI recusados
Quando você implanta o documento da OpenAPI usando gcloud endpoints services deploy
, o Endpoints rejeita documentos da OpenAPI que incluem:
- parâmetros do corpo da matriz como:
parameters: - name: message description: "Message to echo" in: body schema: type: array items: type: string
- caminhos com barras no final, por exemplo:
paths: "/echo/": post: description: "Echo back a given message."
Para corrigir esse erro, remova a barra final de
/echo/
:paths: "/echo": post: description: "Echo back a given message."
Limitações da definição da chave de API
Ao especificar uma chave de API no objeto de definições de segurança no documento da OpenAPI, o Endpoints exige um dos seguintes esquemas:
- O
name
ékey
e oin
équery
- O
name
éapi_key
, e oin
équery
- O
name
éx-api-key
, e oin
éheader
Exemplo:
"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"
},
}
Quando você implanta um documento da OpenAPI com outros tipos de definições de segurança da chave de API, o Endpoints pode aceitá-los e exibir um aviso. No entanto, as definições de segurança da chave de API são ignoradas nas solicitações recebidas.
O portal do Cloud Endpoints não renderiza tipos de composição
Embora o Endpoints aceite documentos da OpenAPI com tipos de composição, ou seja, tipos com allOf
na definição, o portal do Endpoints não gera documentação para tipos de composição.