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]