Merge pull request #617 from danistrebel/features/endpoints-importer

feat: cloud endpoints importer

CODEOWNERS

@@ -24,14 +24,15 @@
 /references/recaptcha-enterprise        @joelgauci
 /references/southbound-mtls             @danistrebel
 /references/threat-protect              @joelgauci
+/tools/apigee-envoy-quickstart          @ganadurai
 /tools/apigee-openlegacy                @tomfi @joelgauci
 /tools/apigee-sackmesser                @danistrebel
 /tools/apigee-x-trial-provision         @yuriylesyuk @danistrebel
 /tools/decrypt-hybrid-assets            @yuriylesyuk
+/tools/endpoints-oas-importer           @danistrebel
 /tools/hybrid-quickstart                @danistrebel
 /tools/oas-apigee-mock                  @markjkelly
 /tools/oas-configurable-proxy           @danistrebel
 /tools/pipeline-linter                  @seymen @danistrebel
 /tools/pipeline-runner                  @seymen @danistrebel
-/tools/sf-dependency-list               @yuriylesyuk
-/tools/apigee-envoy-quickstart          @ganadurai
+/tools/sf-dependency-list               @yuriylesyuk

README.md

@@ -84,6 +84,9 @@ Apigee products.
 - [OpenAPI to Configurable Proxy](tools/oas-configurable-proxy) -
   A tool to generate configurable proxy archives from an OpenAPI
   Specification
+- [Cloud Endpoints OpenAPI Importer](tools/endpoints-oas-importer) -
+  A utility to generate Apigee Proxies based on OAS with Cloud Endpoints OAS
+  extensions
 - [Generate Shared Flows Dependency List](tools/sf-dependency-list) -
   A tool to generate topologically sorted Shared Flow dependencies.
 - [Apigee Envoy Quickstart Toolkit](tools/apigee-envoy-quickstart) -

tools/endpoints-oas-importer/README.md

@@ -0,0 +1,47 @@
+# Cloud Endpoints to Apigee Proxy Bundle Importer
+
+Cloud Endpoints adds a number of OpenAPI [extensions](https://cloud.google.com/endpoints/docs/openapi/openapi-extensions)
+that are used to configure the API proxy behavior.
+
+This tool can be used to import an OpenAPI specification with cloud Cloud
+Endpoints extensions to generate Apigee proxies.
+
+## Prerequisites
+
+* [jq](https://github.com/stedolan/jq) (needed to process OAS in JSON and YAML format)
+* [yq](https://github.com/mikefarah/yq) (only needed to process OAS in YAML format)
+
+## What is currently supported
+
+* default target backend via `x-google-backend.address`
+  and `x-google-backend.path_translation`
+* path level dynamic routing via `x-google-backend.address`
+  and `x-google-backend.path_translation`
+* intercept unmatched paths via `x-google-allow`
+* authenticate towards backend with a Google ID token e.g. for Cloud Run backends
+* authenticate client via JWT through the OAS `x-google-...` security context extensions
+
+## How to use it
+
+The endpoints importer expects the following parameters:
+
+```txt
+--oas/-o            the path of an OpenAPI 2.0 file in json or yaml format
+--base-path/-b      the basepath that should be extracted from
+                    the OAS paths and used in the proxy
+--name/-n           the name of the proxy to be created
+--quiet/-q          (optional) skip the override confirmation
+```
+
+With a JSON OAS file
+
+```sh
+./import-endpoints.sh --oas ./examples/openapi_test.json --base-path /headers --name oas-import-test
+```
+
+With a YAML OAS file
+
+```sh
+./import-endpoints.sh --oas ./examples/openapi_test.yaml --base-path /headers --name oas-import-test
+```
+

tools/endpoints-oas-importer/examples/openapi_test.json

@@ -0,0 +1,64 @@
+{
+  "basePath": "/",
+  "consumes": [
+    "application/json"
+  ],
+
+  "host": "api.example.com",
+  "info": {
+    "description": "Example OAS for Endpoints integration in Apigee.",
+    "title": "Examples - Dynamic Routing",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/ip": {
+      "get": {
+        "description": "Returns the requester's IP.",
+        "operationId": "getIp",
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "Request IP."
+          }
+        },
+        "x-google-backend": {
+          "address": "https://httpbin.org",
+          "deadline": 7,
+          "disable_auth": true,
+          "path_translation": "APPEND_PATH_TO_ADDRESS",
+          "protocol": "h2"
+        }
+      }
+    },
+    "/ip/bar": {
+      "get": {
+        "description": "Returns the mock server JSON response.",
+        "operationId": "mockJSON",
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "Mock JSON."
+          }
+        },
+        "x-google-backend": {
+          "address": "https://mocktarget.apigee.net/json",
+          "deadline": 23,
+          "disable_auth": true,
+          "path_translation": "CONSTANT_ADDRESS",
+          "protocol": "http/1.1"
+        }
+      }
+    }
+  },
+  "produces": [
+    "application/json"
+  ],
+  "schemes": [
+    "https"
+  ],
+  "swagger": "2.0"
+}

tools/endpoints-oas-importer/examples/openapi_test.yaml

@@ -0,0 +1,70 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+---
+swagger: "2.0"
+info:
+  description: 'Example OAS for Endpoints integration in Apigee.'
+  version: 1.0.0
+  title: Examples - Dynamic Routing
+host: api.example.com
+schemes:
+  - "https"
+x-google-allow: all
+x-google-backend:
+  address: https://httpbin.org/anything
+  protocol: h2
+  disable_auth: true
+paths:
+  "/headers":
+    get:
+      description: Returns the request headers.
+      operationId: getHeaders
+      responses:
+        '200':
+          description: Request Headers.
+      x-google-backend:
+        address: https://httpbin.org
+        path_translation: APPEND_PATH_TO_ADDRESS
+        disable_auth: true
+  "/headers/{headerId}/bar":
+    get:
+      description: Returns the mock server JSON response.
+      operationId: mockJSON
+      responses:
+        '200':
+          description: Mock JSON.
+      parameters:
+        - in: path
+          name: headerId
+          type: string
+          required: true
+          description: ID of the header to get
+      x-google-backend:
+        address: https://mocktarget.apigee.net/json
+        disable_auth: true
+        path_translation: CONSTANT_ADDRESS
+  "/headers/{headerId}/foo":
+    get:
+      description: Path entry with default backend.
+      operationId: Foo
+      responses:
+        '200':
+          description: Mock JSON.
+      parameters:
+        - in: path
+          name: headerId
+          type: string
+          required: true
+          description: ID of the header to get