OpenAPI Feature Limitations

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

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

Alternative Security Requirements

Cloud Endpoints does not support alternative (logical OR) security requirements. For example, the following security requirement list is not supported:

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

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

Note however that Cloud Endpoints supports security requirement conjunctions (logical AND). 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.

URL Path Templating

Cloud 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 are not supported.

For example, the following URL path templates are supported:

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

And the following URL path templates are not supported and will be rejected:

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

Operations on URL root path "/"

Cloud Endpoints accepts OpenAPI documents that include operations on the root path "/". However, requests on the root path are rejected by the Extensible Service Proxy (ESP).

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 / will be rejected with the following error:

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

Parameters, Schemas and Types

Cloud Endpoints ignores most parameter and type definitions.

In particular, Cloud Endpoints accepts OpenAPI documents that include required parameter and type definitions, but these definitions are not enforced in incoming requests. Following is a partial list that provides examples of the definitions that Cloud Endpoints accepts but does not 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

Cloud Endpoints does not support references to types outside of an OpenAPI document. For example, Cloud 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

Cloud Endpoints does not allow for custom ports in the host field of an OpenAPI document. For example, Cloud Endpoints rejects OpenAPI documents such as:

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

Known bugs

OpenAPI documents rejected

When you deploy your OpenAPI document via gcloud endpoints services deploy, Cloud 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, remove the trailing slash from `/echo/`:

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

API key limitations

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

  • The name field must be key
  • The in field must be query

For example:

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

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

Send feedback about...

Cloud Endpoints with OpenAPI