[OpenAPI Modification] Return created objects (apache#2603)

As per the ML thread [here](https://lists.apache.org/thread/q7q0rrsmw5gcqv30g4hr9ffq3gtr72yk), this PR introduces the change to return all objects that are created within their respective API calls.

Author: adnanhemani

CHANGELOG.md

@@ -42,6 +42,8 @@ request adding CHANGELOG notes for breaking (!) changes and possibly other secti
 
 ### Changes
 
+* The following APIs will now return the newly-created objects as part of the successful 201 response: createCatalog, createPrincipalRole, createCatalogRole. 
+
 ### Deprecations
 
 * The property `polaris.active-roles-provider.type` is deprecated and has no effect anymore.

regtests/t_catalog_federation/src/catalog_federation.sh

@@ -43,7 +43,7 @@ NEW_CLIENT_SECRET=$(echo "$PRINCIPAL_RESPONSE" | jq -r '.credentials.clientSecre
 
 # Step 2: Create local catalog
 echo "Creating local catalog..."
-RESPONSE_CODE=$(curl -s -X POST -H "Authorization: Bearer ${SPARK_BEARER_TOKEN}" -H 'Content-Type: application/json' \
+RESPONSE_CODE=$(curl -s -o /dev/null -X POST -H "Authorization: Bearer ${SPARK_BEARER_TOKEN}" -H 'Content-Type: application/json' \
   http://${POLARIS_HOST:-localhost}:8181/api/management/v1/catalogs \
   -d '{
     "type": "INTERNAL",
@@ -87,7 +87,7 @@ echo "Assign service_admin to new-user response code: $RESPONSE_CODE"
 
 # Step 4: Create external catalog
 echo "Creating external catalog (passthrough facade)..."
-RESPONSE_CODE=$(curl -s -X POST -H "Authorization: Bearer ${SPARK_BEARER_TOKEN}" -H 'Content-Type: application/json' \
+RESPONSE_CODE=$(curl -s -o /dev/null -X POST -H "Authorization: Bearer ${SPARK_BEARER_TOKEN}" -H 'Content-Type: application/json' \
   http://${POLARIS_HOST:-localhost}:8181/api/management/v1/catalogs \
   -d "{
     \"type\": \"EXTERNAL\",

runtime/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceImpl.java

@@ -126,7 +126,7 @@ public Response createCatalog(
     validateExternalCatalog(catalog);
     Catalog newCatalog = CatalogEntity.of(adminService.createCatalog(request)).asCatalog();
     LOGGER.info("Created new catalog {}", newCatalog);
-    return Response.status(Response.Status.CREATED).build();
+    return Response.status(Response.Status.CREATED).entity(newCatalog).build();
   }
 
   private void validateClientId(String clientId) {
@@ -338,7 +338,7 @@ public Response createPrincipalRole(
     PrincipalRole newPrincipalRole =
         new PrincipalRoleEntity(adminService.createPrincipalRole(entity)).asPrincipalRole();
     LOGGER.info("Created new principalRole {}", newPrincipalRole);
-    return Response.status(Response.Status.CREATED).build();
+    return Response.status(Response.Status.CREATED).entity(newPrincipalRole).build();
   }
 
   /** From PolarisPrincipalRolesApiService */
@@ -394,7 +394,7 @@ public Response createCatalogRole(
     CatalogRole newCatalogRole =
         new CatalogRoleEntity(adminService.createCatalogRole(catalogName, entity)).asCatalogRole();
     LOGGER.info("Created new catalogRole {}", newCatalogRole);
-    return Response.status(Response.Status.CREATED).build();
+    return Response.status(Response.Status.CREATED).entity(newCatalogRole).build();
   }
 
   /** From PolarisCatalogsApiService */

spec/polaris-management-service.yml

@@ -63,6 +63,10 @@ paths:
       responses:
         201:
           description: "Successful response"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Catalog"
         403:
           description: "The caller does not have permission to create a catalog"
         404:
@@ -400,6 +404,10 @@ paths:
       responses:
         201:
           description: "Successful response"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrincipalRole"
         403:
           description: "The caller does not have permission to add a principal role"
 
@@ -613,6 +621,10 @@ paths:
       responses:
         201:
           description: "Successful response"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CatalogRole"
         403:
           description: "The principal is not authorized to create roles"
         404: