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: []
Validação da definição de segurança
O ESP não valida se todos os requisitos de segurança
no nível da API ou do método), também estão presentes no
Seção securityDefinitions
. Como resultado, se a especificação da API usar um
esquema de segurança indefinido, as solicitações não autenticadas poderão ser enviadas pela API no
nível em que a chave de segurança indefinida está configurada. Verifique se todas as chaves de segurança usadas pela API e pelos métodos dela estão definidas nas definições de segurança do documento da OpenAPI.
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."
}
Upload de arquivo
Os endpoints não aceitam type: file
para upload de arquivos.
parâmetros, use type: string
.
Por exemplo, o snippet type: file
a seguir não é permitido:
paths:
/upload:
post:
summary: Uploads a file.
consumes:
- multipart/form-data
parameters:
- in: formData
name: upfile
type: file
description: The file to upload.
Já o seguinte com type: string
é permitido:
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 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
Limitações de alias do YAML
Os endpoints aceitam até 200 nós de alias YAML em uma documento da OpenAPI. Se houver mais de 200 aliases de YAML em uma OpenAPI , recomendamos remover as referências sempre que possível para obedecer a essa ou ao atingir um limite estabelecido.
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.