Limitações do recurso OpenAPI

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: []

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 Beta é 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."
}

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

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 chave de API

Ao especificar uma chave de API no objeto de definições de segurança no seu documento da OpenAPI, o Endpoints exige isto:

  • O campo name precisa ser key.
  • O campo in precisa ser query.

Exemplo:

"securityDefinitions": {
  "api_key": {
    "type": "apiKey",
    "name": "key",
    "in": "query"
  }

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.