[#2242] docs(open-api): Add the open-api for access control

docs/open-api/groups.yaml

@@ -0,0 +1,191 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you 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.
+#
+
+---
+
+paths:
+
+  /metalakes/{metalake}/groups:
+    parameters:
+      - $ref: "./openapi.yaml#/components/parameters/metalake"
+
+    post:
+      tags:
+        - access control
+      summary: Add group
+      operationId: addGroup
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GroupAddRequest"
+            examples:
+              GroupAddRequest:
+                $ref: "#/components/examples/GroupAddRequest"
+
+      responses:
+        "200":
+          description: Returns the added group object
+          content:
+            application/vnd.gravitino.v1+json:
+              schema:
+                $ref: "#/components/responses/GroupResponse"
+              examples:
+                GroupResponse:
+                  $ref: "#/components/examples/GroupResponse"
+        "409":
+          description: Conflict - The target group already exists in the specified metalake
+          content:
+            application/vnd.gravitino.v1+json:
+              schema:
+                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+              examples:
+                GroupAlreadyExistsException:
+                  $ref: "#/components/examples/GroupAlreadyExistsException"
+        "5xx":
+          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+  /metalakes/{metalake}/groups/{group}:
+    parameters:
+      - $ref: "./openapi.yaml#/components/parameters/metalake"
+      - $ref: "./openapi.yaml#/components/parameters/group"
+
+    get:
+      tags:
+        - access control
+      summary: Get group
+      operationId: getGroup
+      description: Returns the specified group information in the specified metalake
+      responses:
+        "200":
+          description: Returns the group object
+          content:
+            application/vnd.gravitino.v1+json:
+              schema:
+                $ref: "#/components/responses/GroupResponse"
+                examples:
+                  GroupResponse:
+                    $ref: "#/components/examples/GroupResponse"
+        "404":
+          description: Not Found - The specified group does not exist in the specified metalake
+          content:
+            application/vnd.gravitino.v1+json:
+              schema:
+                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+              examples:
+                NoSuchMetalakeException:
+                  $ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+                NoSuchGroupException:
+                  $ref: "#/components/examples/NoSuchGroupException"
+        "5xx":
+          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+    delete:
+      tags:
+        - access control
+      summary: Remove group
+      operationId: removeGroup
+      responses:
+        "200":
+          $ref: "./openapi.yaml#/components/responses/RemoveResponse"
+        "400":
+          $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+        "5xx":
+          $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+components:
+
+  schemas:
+    Group:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: The name of the group
+        roles:
+          type: array
+          items:
+            type: string
+          description: The roles of the group
+        audit:
+          $ref: "./openapi.yaml#/components/schemas/Audit"
+
+    GroupAddRequest:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: The name of the group
+
+  responses:
+    GroupResponse:
+      type: object
+      properties:
+        code:
+          type: integer
+          format: int32
+          description: Status code of the response
+          enum:
+            - 0
+        group:
+          $ref: "#/components/schemas/Group"
+
+  examples:
+    GroupAddRequest:
+      value: {
+        "name": "group1",
+      }
+
+    GroupResponse:
+      value: {
+        "code": 0,
+        "group": {
+          "name": "group1",
+          "roles": [],
+          "audit": {
+            "creator": "gravitino",
+            "createTime": "2023-12-08T06:41:25.595Z"
+          },
+        }
+      }
+
+    GroupAlreadyExistsException:
+      value: {
+        "code": 1004,
+        "type": "GroupAlreadyExistsException",
+        "message": "Group already exists",
+        "stack": [
+          "org.apache.gravitino.exceptions.GroupAlreadyExistsException: Group already exists: group1"
+        ]
+      }
+
+    NoSuchGroupException:
+      value: {
+        "code": 1003,
+        "type": "NoSuchGroupException",
+        "message": "Group does not exist",
+        "stack": [
+          "org.apache.gravitino.exceptions.NoSuchGroupException: Group does not exist",
+          "..."
+        ]
+      }

docs/open-api/openapi.yaml

@@ -109,6 +109,40 @@ paths:
   /metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/topics/{topic}:
     $ref: "./topics.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1topics~1%7Btopic%7D"
 
+
+  /metalakes/{metalake}/users:
+    $ref: "./users.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1users"
+
+  /metalakes/{metalake}/users/{user}:
+    $ref: "./users.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1users~1%7Buser%7D"
+
+  /metalakes/{metalake}/groups:
+    $ref: "./groups.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1groups"
+
+  /metalakes/{metalake}/groups/{group}:
+    $ref: "./groups.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1groups~1%7Bgroup%7D"
+
+  /metalakes/{metalake}/roles:
+    $ref: "./roles.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1roles"
+
+  /metalakes/{metalake}/roles/{role}:
+    $ref: "./roles.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1roles~1%7Brole%7D"
+
+  /metalakes/{metalake}/owners/{metadataObjectType}/{metadataObjectFullName}:
+    $ref: "./owners.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1owners~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D"
+
+  /metalakes/{metalake}/permissions/users/{user}/grant:
+    $ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1users~1%7Buser%7D~1grant"
+
+  /metalakes/{metalake}/permissions/users/{user}/revoke:
+    $ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1users~1%7Buser%7D~1revoke"
+
+  /metalakes/{metalake}/permissions/groups/{group}/grant:
+    $ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1groups~1%7Bgroup%7D~1grant"
+
+  /metalakes/{metalake}/permissions/groups/{group}/revoke:
+    $ref: "./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1groups~1%7Bgroup%7D~1revoke"
+
 components:
 
   schemas:
@@ -254,6 +288,57 @@ components:
                 type: boolean
                 description: Whether the drop operation was successful
 
+    RemoveResponse:
+      description: Represents a response for a remove operation
+      content:
+        application/vnd.gravitino.v1+json:
+          schema:
+            type: object
+            properties:
+              code:
+                type: integer
+                format: int32
+                description: Status code of the response
+                enum:
+                  - 0
+              removed:
+                type: boolean
+                description: Whether the remove operation was successful
+
+    DeleteResponse:
+      description: Represents a response for a delete operation
+      content:
+        application/vnd.gravitino.v1+json:
+          schema:
+            type: object
+            properties:
+              code:
+                type: integer
+                format: int32
+                description: Status code of the response
+                enum:
+                  - 0
+              deleted:
+                type: boolean
+                description: Whether the delete operation was successful
+
+    SetResponse:
+      description: Represents a response for a set operation
+      content:
+        application/vnd.gravitino.v1+json:
+          schema:
+            type: object
+            properties:
+              code:
+                type: integer
+                format: int32
+                description: Status code of the response
+                enum:
+                  - 0
+              set:
+                type: boolean
+                description: Whether the set operation was successful
+
   parameters:
     metalake:
       name: metalake
@@ -311,6 +396,29 @@ components:
       schema:
         type: string
 
+    user:
+      name: user
+      in: path
+      description: The name of the user
+      required: true
+      schema:
+        type: string
+
+    group:
+      name: group
+      in: path
+      description: The name of the group
+      required: true
+      schema:
+          type: string
+    role:
+      name: role
+      in: path
+      description: The name of the role
+      required: true
+      schema:
+        type: string
+
     metadataObjectType:
       name: metadataObjectType
       in: path
@@ -324,6 +432,8 @@ components:
           - "table"
           - "fileset"
           - "topic"
+          - "role"
+          - "metalake"
 
     metadataObjectFullName:
       name: metadataObjectFullName