Limitações de recursos da OpenAPI 2.0

As seções abaixo descrevem as limitações dos recursos da OpenAPI 2.0 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), o Extensible Service Proxy V2 (ESPv2) 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 e o ESPv2.

Requisitos de segurança que contêm uma chave de API

O ESP e o ESPv2 não aceitam requisitos de segurança alternativa (OR lógico) quando um dos esquemas de segurança é uma chave de API. Por exemplo, o ESP e o ESPv2 não aceitam 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 e o ESPv2 aceitam 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 e o ESPv2 aceitam 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 e o ESPv2 não validam se todos os requisitos de segurança (no nível da API ou do método) também estão presentes na seção securityDefinitions. Como resultado, se a especificação da API usar um esquema de segurança indefinido, solicitações não autenticadas poderão passar 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 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 o type: file para parâmetros de upload de arquivos. Em vez disso, use type: string.

Por exemplo, o seguinte snippet type: file 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 e o ESPv2 ignoram a maioria das definições de parâmetro e tipo.

O Endpoints aceita documentos OpenAPI que incluem parâmetros e definições de tipo obrigatórias, mas o ESP e o ESPv2 não restringem essas definições e encaminham as solicitações à API. Confira a seguir uma lista parcial com exemplos de definições que o ESP e o ESPv2 não restringem:

  • 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

O Endpoints pode aceitar até 200 nós de alias YAML em um documento da OpenAPI. Se houver mais de 200 aliases YAML em um documento OpenAPI, recomendamos remover a referência dos aliases sempre que possível para obedecer a esse limite.

Bugs conhecidos

Confira a seguir uma lista de problemas 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 o in é query
  • O name é api_key, e o in é query
  • O name é x-api-key, e o in é 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.