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 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 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 os métodos dela estão definidos de acordo com as definições de segurança no 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

Como os endpoints não aceitam type: file para parâmetros de upload de arquivos, use type: string.

Por exemplo, o snippet de 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 exemplo a seguir 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 incluem definições de parâmetro e tipo necessárias, mas o ESP não aplica essas definições e encaminha as solicitações recebidas para a API. Veja a seguir uma lista parcial com exemplos das definições que o ESP não aplica:

• 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 do 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 desreferenciar 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.

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.