Copilot commented on code in PR #14667:
URL: https://github.com/apache/gravitino/pull/14667#discussion_r4478663497


##########
docs/open-api/filesets.yaml:
##########
@@ -348,17 +403,32 @@ components:
           nullable: true
         storageLocations:
           type: object
-          description: The storage locations of the fileset. If the storage 
location of managed fileset is empty, \
-            it will use the location of namespace. The storage locations of 
external fileset must be set.
+          description: >-
+            The named storage locations of the fileset. If the storage 
location of a managed
+            fileset is empty, it uses the location of the namespace. External 
filesets must
+            specify storage locations. When the resulting fileset has more 
than one location,
+            including inherited locations, properties must include 
default-location-name
+            with a value matching one of the resolved location keys.

Review Comment:
   These descriptions mix "namespace" and "schema" as inheritance sources 
("location of the namespace" vs "inherit locations from the catalog or 
schema"). If those are meant to be the same concept in this API, it would be 
clearer to use one term consistently; if they differ, the docs should explain 
when inheritance comes from each and the resolution order (catalog vs 
schema/namespace vs request).



##########
docs/open-api/openapi.yaml:
##########
@@ -422,6 +422,44 @@ components:
             "message": "Malformed request"
           }
 
+    ForbiddenErrorResponse:
+      description: >-
+        Forbidden - The caller is not allowed to perform the operation. When 
authorization
+        is enabled, a missing metalake or a caller who is not a member of the 
metalake
+        also returns 403.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorModel"
+          example:
+            code: 1008
+            type: ForbiddenException
+            message: Current user alice is not a member of metalake metalake1, 
or the metalake does not exist
+
+    NotAcceptableErrorResponse:
+      description: >-
+        Not Acceptable - The requested API version is unsupported, or the 
effective
+        Accept header cannot be served by this operation. When Accept has no 
Gravitino
+        API version, including application/json, */*, or an absent header, the 
server
+        uses the version from Content-Type if present, otherwise the default 
API version.
+        An unsupported version returns IllegalArgumentException; failed 
content negotiation
+        returns RESTException.

Review Comment:
   The description documents server-side exception class names 
("IllegalArgumentException", "RESTException"). This tends to be brittle and can 
confuse API consumers because it ties the contract to implementation details. 
Consider describing the behavior purely in terms of HTTP status + ErrorModel 
fields (e.g., the "type" values you already show in examples), without 
referencing internal exception classes.



##########
docs/open-api/topics.yaml:
##########
@@ -35,6 +35,12 @@ paths:
           $ref: "./openapi.yaml#/components/responses/EntityListResponse"
         "400":
           $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+        "403":
+          $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+        "406":
+          $ref: 
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+        "501":
+          $ref: "#/components/responses/TopicUnsupportedOperationErrorResponse"
         "5xx":
           $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

Review Comment:
   "5xx" is not a valid response code pattern in OpenAPI 3.x (the spec allows 
"5XX" or "default"). Some tooling will reject or ignore this response mapping. 
Consider changing "5xx" to "5XX" (or "default") consistently across the spec.



##########
docs/open-api/filesets.yaml:
##########
@@ -51,9 +53,27 @@ paths:
             examples:
               FilesetCreateRequest:
                 $ref: "#/components/examples/FilesetCreateRequest"
+              MultipleLocationsFilesetCreateRequest:
+                $ref: 
"#/components/examples/MultipleLocationsFilesetCreateRequest"
       responses:
         "200":
           $ref: "#/components/responses/FilesetResponse"
+        "400":
+          description: >-
+            Bad Request - The fileset creation request is invalid. For 
multiple storage
+            locations, properties.default-location-name must name one of the 
location keys.
+          content:
+            application/json:
+              schema:
+                $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+              example:
+                code: 1001
+                type: IllegalArgumentException
+                message: >-
+                  The fileset property default-location-name must be set and 
must be one of
+                  the fileset locations, location names: [primary, secondary], 
default location name: null

Review Comment:
   This introduces an inline 400 response shape/example that is specific to one 
validation failure, while other operations reuse shared 400 components. To keep 
the spec consistent and easier to maintain, consider extracting this into a 
named component response (e.g., a dedicated FilesetCreateBadRequest response) 
and referencing it here, or adding it as an additional named example under the 
shared BadRequestErrorResponse if that component is intended to cover this case.



##########
docs/open-api/filesets.yaml:
##########
@@ -348,17 +403,32 @@ components:
           nullable: true
         storageLocations:
           type: object
-          description: The storage locations of the fileset. If the storage 
location of managed fileset is empty, \
-            it will use the location of namespace. The storage locations of 
external fileset must be set.
+          description: >-
+            The named storage locations of the fileset. If the storage 
location of a managed
+            fileset is empty, it uses the location of the namespace. External 
filesets must
+            specify storage locations. When the resulting fileset has more 
than one location,
+            including inherited locations, properties must include 
default-location-name
+            with a value matching one of the resolved location keys.
           nullable: true
           default: { }
           additionalProperties:
             type: string
         properties:
           type: object
-          description: The properties of the fileset. Can be empty.
+          description: >-
+            The properties of the fileset. When the resulting fileset has 
multiple storage locations,
+            default-location-name is required and must match one of the 
resolved location keys;
+            otherwise creation returns HTTP 400. Managed filesets may inherit 
locations from the
+            catalog or schema even when storageLocations is omitted.

Review Comment:
   These descriptions mix "namespace" and "schema" as inheritance sources 
("location of the namespace" vs "inherit locations from the catalog or 
schema"). If those are meant to be the same concept in this API, it would be 
clearer to use one term consistently; if they differ, the docs should explain 
when inheritance comes from each and the resolution order (catalog vs 
schema/namespace vs request).



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to