OpenAPI 3.x feature limitations

This document describes the feature limitations for using OpenAPI 3.x with API Gateway.

For more information on supported OpenAPI specification versions, see OpenAPI overview.

New OpenAPI 3.x Limitations

This section describes limitations for features new in OpenAPI 3.x.

Servers

OpenAPI 3.x supports multiple server objects to define hosts and base paths. However, API Gateway relies on a single server object, identified by the x-google-endpoint extension, to configure the service.

While you can define multiple servers, API Gateway considers only the server that contains the x-google-endpoint extension, and permits only one such server. For API Gateway, a server URL is not required, so you can have either no servers defined or one server with the x-google-endpoint extension.

For example, the following definitions are valid for API Gateway:

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

The following definition is invalid because it contains multiple x-google-endpoint extensions:

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

The following definition is valid for API Gateway, but API Gateway ignores the server object:

servers:
  - url: https://example.com

Servers Across Multiple Files

If you upload multiple OpenAPI files and one file contains a server with the x-google-endpoint extension, then all files must also have a server defined with an identical x-google-endpoint extension and an identical host in the server URL. The basepath may differ between files.

Relative URL

For API Gateway, relative URLs in the servers object are treated as a basepath on their own because a hostname is not required in the specification. This is different from the standard OpenAPI behavior, which resolves relative URLs against the server hosting the OpenAPI definition. For example, API Gateway treats url: /v1 as a basepath.

Basepaths must begin with '/'. API Gateway rejects URLs that don't have a scheme or begin with '/' to indicate a basepath.

Unsupported Extensions

API Gateway does not support the x-google-allow extension for OpenAPI 3.x.

File size limits

API Gateway enforces a total size limit of 10MB and a file count limit of 50 for uploaded OpenAPI 3.x files.

Pre-existing limitations

This section describes limitations carried over from OpenAPI 2.0 that also apply to OpenAPI 3.x.

Scopes ignored

Although API Gateway accepts OpenAPI documents with scopes defined in a security scheme object, API Gateway does not check or enforce these scopes.

Multiple security requirements

API Key Requirements: API Gateway does not support alternative (logical OR) security requirements if one of the schemes is an API key. However, API Gateway supports conjunctions (logical AND), which lets you require both an API key and an OAuth2 token.
OAuth2 Requirements: API Gateway supports alternative (logical OR) security requirements for different OAuth2 security schemes. API Gateway does not support conjunctions (logical AND) unless the additional security requirement is an API key.
Optional Security: You can use an empty security requirement (- {}) to make security optional for an API key, but API Gateway does not support this for OAuth.

Security definition validation

API Gateway will reject an OpenAPI 3.x specification that uses a security requirement without a corresponding definition in the securityDefinitions section.

URL path templating

API Gateway only supports URL path template parameters that represent entire path segments, for example, /items/{itemId}. API Gateway does not support and rejects parameters corresponding to partial segments, for example, /items/prefix_{id}_suffix.

Parameters, schemas, request bodies, and types

API Gateway accepts OpenAPI documents with various parameter and type definitions (for example, required parameters and array formats), but it does not enforce them. API Gateway forwards incoming requests to your API regardless of these definitions.

API Gateway supports only primitive types in request parameters.

External type references

API Gateway does not support references to types outside of the provided OpenAPI document. For example, API Gateway does not allow and rejects a $ref that points to an external URL.

Custom port in host address

API Gateway does not allow custom ports in the servers.url field of an OpenAPI document.

YAML alias limitations

An OpenAPI document submitted to API Gateway can have a maximum of 200 YAML alias nodes.