Esta página foi traduzida pela API Cloud Translation.

Limitações do recurso OpenAPI

OpenAPI | gRPC

O Cloud Endpoints aceita apenas a versão 2 da especificação OpenAPI.

As seções a seguir descrevem 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, nem o Extensible Service Proxy (ESP), nem o Extensible Service Proxy V2 (ESPv2) nem o Endpoints Frameworks verificam os escopos definidos.

Vários requisitos de segurança

É possível especificar mais de um requisito de segurança no documento do OpenAPI. Esta seção descreve 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 são compatíveis com requisitos de segurança alternativos (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 são compatíveis com 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 são compatíveis com requisitos de segurança alternativos (OR lógico), mas apenas para esquemas de segurança 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, 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 parâmetros de upload de arquivos. 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 e o ESPv2 ignoram a maioria das definições de parâmetro e tipo.

O Endpoints aceita documentos OpenAPI que incluam definições de parâmetro e 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 aplicam:

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 podem aceitar até 200 nós de alias YAML em um documento da OpenAPI. Se houver mais de 200 aliases YAML em um documento da OpenAPI, recomendamos que você remova a referência de aliases sempre que possível para obedecer a esse limite.

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 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.