OpenAPI extensions for API Gateway

Extensions (also referred to as specification extensions or vendor extensions) are custom properties that start with x-. These are used to add extra information or functionality that the OpenAPI standard doesn’t include by default.

AWS uses these extensions to map your OpenAPI definition to specific API Gateway features.

• x-amazon-apigateway-integration - Defines the backend integration for an operation, such as connecting to a Lambda function (aws_proxy), an HTTP endpoint, or a mock service.
• x-amazon-apigateway-authorizer - Configures custom authorizers, such as Amazon Cognito user pools or Lambda authorizers, to secure your API.
• x-amazon-apigateway-request-validator - Specifies which validator to use for checking the request body, query strings, and headers against your schema before the request reaches the backend.
• x-amazon-apigateway-cors - Configures Cross-Origin Resource Sharing (CORS) settings for your API resources. x-amazon-apigateway-gateway-responses: Allows you to customize the responses (status codes and body templates) returned by the gateway for errors like “Unauthorized” or “Resource Not Found”.

x-amazon-apigateway-integration

Specifies details of the backend integration used for this method.

See Build API using OpenAPI for more details on how to use this extension in combination with a Spring Cloud Function.

Code example

To use JAX-RS annotations (javax.ws.rs) with OpenAPI extensions, you can apply the @Operation annotation.

In the example below we define a spring cloud function uppercase and use @Operation to include the x-amazon-apigateway-integration extension.

import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.Consumes;
import javax.ws.rs.core.MediaType;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.extensions.Extension;
import io.swagger.v3.oas.annotations.extensions.ExtensionProperty;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.stereotype.Component;
import java.util.function.Function;

@Path("/cdk4j/examples")
@SpringBootApplication
public class Cdk4jSpringCloudApplication {

  public static void main(String[] args) {
    SpringApplication.run(Cdk4jSpringCloudApplication.class, args);
  }

  @Bean
  @POST
  @Path("uppercase")
  @Consumes(MediaType.TEXT_PLAIN)
  @Produces(MediaType.TEXT_PLAIN)
  @Operation(
      summary = "Uppercase Converter",
      description = "Processes a string through the Spring Cloud Function.",
      responses = {
          @ApiResponse(responseCode = "200", description = "Successful transformation")
      },
      // AWS API Gateway vendor extension
      extensions = @Extension(
          name = "x-amazon-apigateway-integration",
          properties = {
              @ExtensionProperty(name = "type", value = "aws_proxy"),
              @ExtensionProperty(name = "httpMethod", value = "POST"),
              @ExtensionProperty(name = "uri", value = "uppercase"),
          }
      )
  )
  public Function<String, String> uppercase() {
    return String::toUpperCase;
  }
}

References

• OpenAPI extensions for API Gateway