From ab20382ff3db761bd1c2217fbacd0de89ff9e29c Mon Sep 17 00:00:00 2001
From: Jerry Shao <jerryshao@datastrato.com>
Date: Mon, 19 Aug 2024 17:14:09 +0800
Subject: [PATCH] [MINOR] fix(doc): Add missing tag api in openAPI (#4579)

### What changes were proposed in this pull request?

This PR proposes to add a missing tag openapi to list all the metadata
objects for a tag.

### Why are the changes needed?

This is missing to add.

### Does this PR introduce _any_ user-facing change?

No.

### How was this patch tested?

Manual verification
---
 docs/open-api/catalogs.yaml |  3 ++
 docs/open-api/openapi.yaml  | 17 ++++---
 docs/open-api/tags.yaml     | 88 +++++++++++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 7 deletions(-)

diff --git a/docs/open-api/catalogs.yaml b/docs/open-api/catalogs.yaml
index ab68c06ed2a..8ec5d0799d0 100644
--- a/docs/open-api/catalogs.yaml
+++ b/docs/open-api/catalogs.yaml
@@ -256,9 +256,12 @@ components:
           enum:
             - hive
             - lakehouse-iceberg
+            - lakehouse-paimon
             - jdbc-mysql
             - jdbc-postgresql
+            - jdbc-doris
             - hadoop
+            - kafka
         comment:
           type: string
           description: A comment about the catalog
diff --git a/docs/open-api/openapi.yaml b/docs/open-api/openapi.yaml
index edac71ec683..a0381bb6e23 100644
--- a/docs/open-api/openapi.yaml
+++ b/docs/open-api/openapi.yaml
@@ -70,6 +70,9 @@ paths:
   /metalakes/{metalake}/tags/{metadataObjectType}/{metadataObjectFullName}/{tag}:
     $ref: "./tags.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1tags~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D~1%7Btag%7D"
 
+  /metalakes/{metalake}/tags/{tag}/objects:
+    $ref: "./tags.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1tags~1%7Btag%7D~1objects"
+
   /metalakes/{metalake}/catalogs:
     $ref: "./catalogs.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs"
 
@@ -427,13 +430,13 @@ components:
       schema:
         type: string
         enum:
-          - "catalog"
-          - "schema"
-          - "table"
-          - "fileset"
-          - "topic"
-          - "role"
-          - "metalake"
+          - "CATALOG"
+          - "SCHEMA"
+          - "TABLE"
+          - "FILESET"
+          - "TOPIC"
+          - "ROLE"
+          - "METALAKE"
 
     metadataObjectFullName:
       name: metadataObjectFullName
diff --git a/docs/open-api/tags.yaml b/docs/open-api/tags.yaml
index 61d9ae1fc84..54db400b408 100644
--- a/docs/open-api/tags.yaml
+++ b/docs/open-api/tags.yaml
@@ -284,6 +284,41 @@ paths:
         "5xx":
           $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
 
+
+  /metalakes/{metalake}/tags/{tag}/objects:
+    parameters:
+      - $ref: "./openapi.yaml#/components/parameters/metalake"
+      - $ref: "./openapi.yaml#/components/parameters/tag"
+    get:
+      tags:
+        - tag
+      summary: list metadata objects for tag
+      operationId: listTagObjects
+      responses:
+        "200":
+          description: Returns the list of metadata objects associated with specified tag
+          content:
+            application/vnd.gravitino.v1+json:
+              schema:
+                $ref: "#/components/responses/MetadataObjectListResponse"
+              examples:
+                TagResponse:
+                  $ref: "#/components/examples/MetadataObjectListResponse"
+        "400":
+          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+        "404":
+          description: Not Found - The specified tag does not exist
+          content:
+            application/vnd.gravitino.v1+json:
+              schema:
+                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+              examples:
+                NoSuchTagException:
+                  $ref: "#/components/examples/NoSuchTagException"
+        "5xx":
+          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+
 components:
   parameters:
     details:
@@ -324,6 +359,25 @@ components:
           description: Whether the tag is inherited from the parent metadata object
           nullable: true
 
+    MetadataObject:
+      type: object
+      description: A metadata object
+      properties:
+        fullName:
+          type: string
+          description: The name of the metadata object, separated by dots
+        type:
+          type: string
+          description: The type of the metadata object
+          enum:
+            - "CATALOG"
+            - "SCHEMA"
+            - "TABLE"
+            - "FILESET"
+            - "TOPIC"
+            - "ROLE"
+            - "METALAKE"
+
 
   requests:
 
@@ -507,6 +561,21 @@ components:
         tag:
           $ref: "#/components/schemas/Tag"
 
+    MetadataObjectListResponse:
+      type: object
+      properties:
+        code:
+          type: integer
+          format: int32
+          description: Status code of the response
+          enum:
+            - 0
+        metadataObjects:
+          type: array
+          description: A list of metadata objects
+          items:
+            $ref: "#/components/schemas/MetadataObject"
+
   examples:
     NameListResponse:
       value: {
@@ -580,6 +649,25 @@ components:
         }
       }
 
+    MetadataObjectListResponse:
+      value: {
+        "code": 0,
+        "metadataObjects": [
+          {
+            "type": "CATALOG",
+            "fullName":"my_catalog",
+          },
+          {
+            "type": "SCHEMA",
+            "fullName":"my_catalog.my_schema",
+          },
+          {
+            "type": "TABLE",
+            "fullName":"my_catalog.my_schema.my_table",
+          }
+        ]
+      }
+
     TagAlreadyExistsException:
       value: {
         "code": 1004,