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

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.

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

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

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 limitations

When specifying an API key in the security definitions object in your OpenAPI document, 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, 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.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI
Need help? Visit our support page.