OpenAPI feature limitations

Currently, Cloud Endpoints accepts only version 2 of the OpenAPI Specification.

The sections below describe the limitations of OpenAPI features on Endpoints.

Scopes ignored

Although Endpoints accepts OpenAPI documents that have scopes defined in a security scheme object, when a request is sent to your API, neither the Extensible Service Proxy (ESP) nor Cloud Endpoints Frameworks check the defined scopes.

Multiple security requirements

You can specify more than one security requirement in your OpenAPI document. This section describes the security schemes that ESP supports.

Security requirements containing an API key

ESP doesn't support alternative (logical OR) security requirements when one of the security schemes is an API key. For example, ESP doesn't support the following security requirement list:

security:
- petstore_auth: []
- api_key: []

This definition requires an operation to accept requests that follow the petstore_auth requirements or the api_key requirements.

Note, however, that ESP supports security requirement conjunctions (logical AND), so you can require both an API key and OAuth2 authentication. For example, the following security requirement list is supported:

security:
- petstore_auth: []
  api_key: []

This definition requires an operation to accept requests that simultaneously follow the petstore_auth requirements and the api_key requirements.

Security requirements for OAuth2

ESP supports security alternative (logical OR) security requirements, but only for OAuth2 authentication security schemes. For example, the following security requirement list is supported:

security:
  - firebase1: []
  - firebase2: []

Security definition validation

ESP doesn't validate that all the security requirements (either at the API level or method level), also are present under the securityDefinitions section. As a result, if the API specification uses an undefined security schema, unauthenticated requests may come through the API, on the level where the undefined security key is configured. Make sure that all security keys used by your API and its methods are defined under the security definitions in your OpenAPI document.

URL path templating

Endpoints only supports URL path template parameters that correspond to entire path segments (delimited by slashes /). URL path template parameters that correspond to partial path segments aren't supported.

For example, the following URL path templates are supported:

  • /items/{itemId}
  • /items/{itemId}/subitems

The following URL path templates aren't supported and will be rejected:

  • /items/overview.{format}
  • /items/prefix_{id}_suffix

Operations on URL root path /

Endpoints accepts OpenAPI documents that include operations on the root path /. However, requests on the root path are rejected by ESP. Note, this limitation is only for ESP, ESPv2 supports root path /.

For example, the following OpenAPI document snippet is accepted:

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

But subsequent requests for POST / are rejected with the following error:

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

File upload

Endpoints does not accept the type: file for file upload parameters, type: string should be used instead.

For example, the following type: file snippet is not allowed:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

Whereas the following with type: string is allowed:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

Parameters, schemas, and types

ESP ignores most parameter and type definitions.

Endpoints accepts OpenAPI documents that include required parameter and type definitions, but ESP doesn't enforce these definitions and forwards incoming requests to your API. The following is a partial list that provides examples of the definitions that ESP doesn't enforce:

  • Form Data parameters, such as:
    parameters:
    - name: avatar
      in: formData
      description: "The avatar of the user"
      type: string
  • Required parameters, such as:
    parameters:
    - name: message
      in: query
      description: "Message to send"
      required: true
      type: string
  • Array collection formats, such as:
    parameters:
    - name: items
      in: query
      description: "List of item IDs"
      required: true
      type: array
      items:
        type: string
      collectionFormat: tsv
  • Type composition, such as:
    definitions:
      base:
        properties:
          message:
            type: string
      extended:
        description: "Extends the base type"
        allOf:
        - $ref: "#/definitions/base"
        - type: object
          properties:
            extension:
              type: string
  • Different response objects per status code, such as:
    responses:
      200:
        description: "Echo"
        schema:
          $ref: "#/definitions/EchoResponse"
      400:
        description: "Error"
        schema:
          type: string

External type references

Endpoints doesn't support references to types outside of an OpenAPI document. For example, Endpoints rejects OpenAPI documents that include:

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

Custom port in service host address

Endpoints doesn't allow for custom ports in the host field of an OpenAPI document. For example, Endpoints rejects OpenAPI documents such as:

swagger: 2.0
host: example.com:8080
schemes:
- http

YAML alias limitations

Endpoints can support up to 200 YAML alias nodes in an OpenAPI document. If there are more than 200 YAML aliases in an OpenAPI document, we recommend de-referencing aliases where possible to comply with this limit.

Known bugs

OpenAPI documents rejected

When you deploy your OpenAPI document by using gcloud endpoints services deploy, Endpoints rejects OpenAPI documents that include:

  • Array body parameters, such as:
    parameters:
    - name: message
      description: "Message to echo"
      in: body
      schema:
        type: array
        items:
          type: string
  • Paths with trailing slashes, for example:
    paths:
      "/echo/":
        post:
          description: "Echo back a given message."
    

    To fix this issue, remove the trailing slash from /echo/:

    paths:
      "/echo":
        post:
          description: "Echo back a given message."
    

API key definition limitations

When specifying an API key in the security definitions object in your OpenAPI document, Endpoints requires one of the following schemes:

  • The name is key and the in is query
  • The name is api_key and the in is query
  • The name is x-api-key and the in is header

For example:

"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"
    },
}

When you deploy an OpenAPI document with other types of API key security definitions, Endpoints might accept them and output a warning. However, the API key security definitions are ignored in incoming requests.

Cloud Endpoints Portal doesn't render composition types

Although Endpoints accepts OpenAPI documents with composition types, that is, types with allOf in the definition, Endpoints Portal doesn't generate documentation for composition types.