Merge pull request #201478 from ninpan-ms/ninpan/gateway-openapi

Add openapi uri property to gateway

Author: laurabren

articles/spring-cloud/how-to-set-up-sso-with-azure-ad.md

@@ -1,7 +1,7 @@
 ---
-title: How to set up Single Sign-on with Azure AD for Spring Cloud Gateway and API Portal for Tanzu
+title: How to set up single sign-on with Azure AD for Spring Cloud Gateway and API Portal for Tanzu
 titleSuffix: Azure Spring Apps Enterprise Tier
-description: How to set up Single Sign-on with Azure Active Directory for Spring Cloud Gateway and API Portal for Tanzu with Azure Spring Apps Enterprise Tier.
+description: How to set up single sign-on with Azure Active Directory for Spring Cloud Gateway and API Portal for Tanzu with Azure Spring Apps Enterprise Tier.
 author: karlerickson
 ms.author: ninpan
 ms.service: spring-cloud
@@ -10,18 +10,17 @@ ms.date: 05/20/2022
 ms.custom: devx-track-java, devx-track-azurecli
 ---
 
-# Set up Single Sign-on using Azure Active Directory for Spring Cloud Gateway and API Portal
+# Set up single sign-on using Azure Active Directory for Spring Cloud Gateway and API Portal
 
 **This article applies to:** ❌ Basic/Standard tier ✔️ Enterprise tier
 
-This article shows you how to configure Single Sign-on (SSO) for Spring Cloud Gateway or API Portal using the Azure Active Directory (Azure AD) as an OpenID identify provider.
+This article shows you how to configure single sign-on (SSO) for Spring Cloud Gateway or API Portal using the Azure Active Directory (Azure AD) as an OpenID identify provider.
 
 ## Prerequisites
 
 - An Enterprise tier instance with Spring Cloud Gateway or API portal enabled. For more information, see [Quickstart: Provision an Azure Spring Apps service instance using the Enterprise tier](quickstart-provision-service-instance-enterprise.md).
 - Sufficient permissions to manage Azure AD applications.
 
-
 To enable SSO for Spring Cloud Gateway or API Portal, you need the following four properties configured:
 
 | SSO Property | Azure AD Configuration |

articles/spring-cloud/how-to-use-enterprise-api-portal.md

@@ -19,7 +19,7 @@ ms.custom: devx-track-java, devx-track-azurecli, event-tier1-build-2022
 
 This article shows you how to use API portal for VMware Tanzu® with Azure Spring Apps Enterprise Tier.
 
-[API portal](https://docs.vmware.com/en/API-portal-for-VMware-Tanzu/1.0/api-portal/GUID-index.html) is one of the commercial VMware Tanzu components. API portal supports viewing API definitions from [Spring Cloud Gateway for VMware Tanzu®](./how-to-use-enterprise-spring-cloud-gateway.md) and testing of specific API routes from the browser. It also supports enabling Single Sign-on authentication via configuration.
+[API portal](https://docs.vmware.com/en/API-portal-for-VMware-Tanzu/1.0/api-portal/GUID-index.html) is one of the commercial VMware Tanzu components. API portal supports viewing API definitions from [Spring Cloud Gateway for VMware Tanzu®](./how-to-use-enterprise-spring-cloud-gateway.md) and testing of specific API routes from the browser. It also supports enabling single sign-on (SSO) authentication via configuration.
 
 ## Prerequisites
 
@@ -34,9 +34,9 @@ This article shows you how to use API portal for VMware Tanzu® with Azure Sprin
 
 The following sections describe configuration in API portal.
 
-### Configure single Sign-on (SSO)
+### Configure single sign-on (SSO)
 
-API portal supports authentication and authorization using single Sign-on (SSO) with an OpenID identity provider (IdP) that supports the OpenID Connect Discovery protocol.
+API portal supports authentication and authorization using single sign-on (SSO) with an OpenID identity provider (IdP) that supports the OpenID Connect Discovery protocol.
 
 > [!NOTE]
 > Only authorization servers supporting the OpenID Connect Discovery protocol are supported. Be sure to configure the external authorization server to allow redirects back to the gateway. Refer to your authorization server's documentation and add `https://<gateway-external-url>/login/oauth2/code/sso` to the list of allowed redirect URIs.
@@ -48,7 +48,7 @@ API portal supports authentication and authorization using single Sign-on (SSO)
 | clientSecret | Yes | The OpenID Connect client secret provided by your IdP |
 | scope | Yes | A list of scopes to include in JWT identity tokens. This list should be based on the scopes allowed by your identity provider |
 
-To set up SSO with Azure AD, see [How to set up Single Sign-on with Azure AD for Spring Cloud Gateway and API Portal for Tanzu](./how-to-set-up-sso-with-azure-ad.md).
+To set up SSO with Azure AD, see [How to set up single sign-on with Azure AD for Spring Cloud Gateway and API Portal for Tanzu](./how-to-set-up-sso-with-azure-ad.md).
 
 > [!NOTE]
 > If you configure the wrong SSO property, such as the wrong password, you should remove the entire SSO property and re-add the correct configuration.
@@ -75,7 +75,73 @@ You can also use the Azure CLI to assign a public endpoint with the following co
 az spring api-portal update --assign-endpoint
 ```
 
-## View the route information through API portal
+## Configure API routing with OpenAPI Spec on Spring Cloud Gateway for Tanzu
+
+This section describes how to view and try out APIs with schema definitions in API portal. Use the following steps to configure API routing with an OpenAPI spec URL on Spring Cloud Gateway for Tanzu.
+
+1. Create an app in Azure Spring Apps that the gateway will route traffic to.
+
+1. Generate the OpenAPI definition and get the URI to access it. The following two URI options are accepted:
+
+   - The first option is to use a publicly accessible endpoint like the URI `https://petstore3.swagger.io/api/v3/openapi.json`, which includes the OpenAPI specification.
+   - The second option is to put the OpenAPI definition in the relative path of the app in Azure Spring Apps, and construct the URI in the format `http://<app-name>/<relative-path-to-OpenAPI-spec>`. You can choose tools like `SpringDocs` to generate the OpenAPI specification automatically, so the URI can be like `http://<app-name>/v3/api-docs`.
+
+1. Use the following command to assign a public endpoint to the gateway to access it.
+
+   ```azurecli
+   az spring gateway update --assign-endpoint
+   ```
+
+1. Use the following command to configure Spring Cloud Gateway for Tanzu properties:
+
+   ```azurecli
+   az spring gateway update \
+       --api-description "<api-description>" \
+       --api-title "<api-title>" \
+       --api-version "v0.1" \
+       --server-url "<endpoint-in-the-previous-step>" \
+       --allowed-origins "*"
+   ```
+
+1. Configure routing rules to apps.
+
+   To create rules to access the app in Spring Cloud Gateway for Tanzu route configuration, save the following contents to the *sample.json* file.
+
+   ```json
+   {
+      "open_api": {
+         "uri": "https://petstore3.swagger.io/api/v3/openapi.json"
+      },
+      "routes": [
+         {
+            "title": "Petstore",
+            "description": "Route to application",
+            "predicates": [
+               "Path=/pet",
+               "Method=PUT"
+            ],
+            "filters": [
+               "StripPrefix=0",
+            ]
+         }
+      ]
+   }
+   ```
+
+   The `open_api.uri` value is the public endpoint or URI constructed in the second step above. You can add predicates and filters for paths defined in your OpenAPI specification.
+
+   Use the following command to apply the rule to the app created in the first step:
+
+   ```azurecli
+   az spring gateway route-config create \
+       --name sample \
+       --app-name <app-name> \
+       --routes-file sample.json
+   ```
+
+1. Check the response of the created routes. You can also view the routes in the portal.
+
+## View exposed APIs in API portal
 
 > [!NOTE]
 > It takes several minutes to sync between Spring Cloud Gateway for Tanzu and API portal.
@@ -84,13 +150,12 @@ Select the `endpoint URL` to go to API portal. You'll see all the routes configu
 
 :::image type="content" source="media/enterprise/how-to-use-enterprise-api-portal/api-portal.png" alt-text="Screenshot of A P I portal showing configured routes.":::
 
-## Try APIs using API portal
+## Try out APIs in API portal
 
-> [!NOTE]
-> Only `GET` operations are supported in the public preview.
+Use the following steps to try out APIs:
 
 1. Select the API you would like to try.
-1. Select **EXECUTE** and the response will be shown.
+1. Select **EXECUTE**, and the response will be shown.
 
    :::image type="content" source="media/enterprise/how-to-use-enterprise-api-portal/api-portal-tryout.png" alt-text="Screenshot of A P I portal.":::