Esta página foi traduzida pela API Cloud Translation.

Limitações do recurso OpenAPI

OpenAPI | gRPC

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

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.