This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch branch-0.9
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-0.9 by this push:
new 89bef53d3b [#6860] docs: add OpenAPI docs for fileset/files (#7356)
89bef53d3b is described below
commit 89bef53d3b95566f5879e1e08e4e20d9bed18bcc
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Sun Jun 8 20:49:33 2025 +0800
[#6860] docs: add OpenAPI docs for fileset/files (#7356)
### What changes were proposed in this pull request?
Add OpenAPI doc for fileset/files endpoint
### Why are the changes needed?
To generate docs for the new API endpoint at fileset/files
Fix: #7328
### Does this PR introduce _any_ user-facing change?
Yes, new REST API doc
### How was this patch tested?
CI pass
Co-authored-by: Yunchi Pang <[email protected]>
---
.../hadoop/integration/test/HadoopCatalogIT.java | 4 +-
docs/open-api/filesets.yaml | 117 +++++++++++++++++++++
docs/open-api/openapi.yaml | 3 +
.../server/web/rest/FilesetOperations.java | 4 +-
4 files changed, 124 insertions(+), 4 deletions(-)
diff --git
a/catalogs/catalog-hadoop/src/test/java/org/apache/gravitino/catalog/hadoop/integration/test/HadoopCatalogIT.java
b/catalogs/catalog-hadoop/src/test/java/org/apache/gravitino/catalog/hadoop/integration/test/HadoopCatalogIT.java
index 0f7c8889ab..dd17969482 100644
---
a/catalogs/catalog-hadoop/src/test/java/org/apache/gravitino/catalog/hadoop/integration/test/HadoopCatalogIT.java
+++
b/catalogs/catalog-hadoop/src/test/java/org/apache/gravitino/catalog/hadoop/integration/test/HadoopCatalogIT.java
@@ -196,10 +196,10 @@ public class HadoopCatalogIT extends BaseIT {
}
if (!StringUtils.isBlank(subPath)) {
- uriBuilder.addParameter("subPath", subPath);
+ uriBuilder.addParameter("sub_path", subPath);
}
if (!StringUtils.isBlank(locationName)) {
- uriBuilder.addParameter("locationName", locationName);
+ uriBuilder.addParameter("location_name", locationName);
}
HttpGet httpGet;
diff --git a/docs/open-api/filesets.yaml b/docs/open-api/filesets.yaml
index db5c5b190d..8a3915c4f3 100644
--- a/docs/open-api/filesets.yaml
+++ b/docs/open-api/filesets.yaml
@@ -205,6 +205,55 @@ paths:
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}/files:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/catalog"
+ - $ref: "./openapi.yaml#/components/parameters/schema"
+ - $ref: "./openapi.yaml#/components/parameters/fileset"
+
+ get:
+ tags:
+ - fileset
+ summary: List files
+ operationId: listFilesetFiles
+ description: List metadata of files and directories in a fileset
+ parameters:
+ - name: sub_path
+ in: query
+ required: false
+ schema:
+ type: string
+ default: "/"
+ description: The sub path within the fileset to list files and
directories from
+ - name: location_name
+ in: query
+ required: false
+ schema:
+ type: string
+ default: null
+ description: The name of the storage location
+ responses:
+ "200":
+ $ref: "#/components/responses/FileInfoListResponse"
+ "404":
+ description: Not Found – the target fileset or subPath or
locationName does not exist
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchCatalogException:
+ $ref:
"./catalogs.yaml#/components/examples/NoSuchCatalogException"
+ NoSuchSchemaException:
+ $ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
+ NoSuchFilesetException:
+ $ref: "#/components/examples/NoSuchFilesetException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
components:
schemas:
@@ -235,6 +284,33 @@ components:
default: {}
additionalProperties:
type: string
+ FileInfo:
+ type: object
+ required:
+ - name
+ - isDir
+ - size
+ - lastModified
+ - path
+ properties:
+ name:
+ type: string
+ description: The name of the file/directory
+ isDir:
+ type: boolean
+ description: Whether this is a directory
+ size:
+ type: integer
+ format: int64
+ description: The file size in bytes (0 if directory)
+ lastModified:
+ type: integer
+ format: int64
+ description: The last modification time of the file/directory
+ path:
+ type: string
+ description: The gvfs path of the file/directory
+
FilesetCreateRequest:
type: object
required:
@@ -411,6 +487,26 @@ components:
FilesetResponse:
$ref: "#/components/examples/FilesetResponse"
+ FileInfoListResponse:
+ description: The response containing a list of file/directory metadata
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum: [0]
+ files:
+ type: array
+ items:
+ $ref: "#/components/schemas/FileInfo"
+ examples:
+ FileInfoListResponse:
+ $ref: "#/components/examples/FileInfoListResponse"
+
FileLocationResponse:
description: The response of the file location object
content:
@@ -459,6 +555,27 @@ components:
}
}
+ FileInfoListResponse:
+ value: {
+ "code": 0,
+ "files": [
+ {
+ "name": "file.txt",
+ "isDir": false,
+ "size": 5,
+ "lastModified": 1748875070123,
+ "path": "/fileset/catalog1/schema1/fileset1/file.txt"
+ },
+ {
+ "name": "sub_dir",
+ "isDir": true,
+ "size": 0,
+ "lastModified": 1748875070124,
+ "path": "/fileset/catalog1/schema1/fileset1/sub_dir"
+ }
+ ]
+ }
+
FileLocationResponse:
value: {
"code": 0,
diff --git a/docs/open-api/openapi.yaml b/docs/open-api/openapi.yaml
index e6047ab9bd..99c5ce3b7c 100644
--- a/docs/open-api/openapi.yaml
+++ b/docs/open-api/openapi.yaml
@@ -110,6 +110,9 @@ paths:
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}:
$ref:
"./filesets.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1filesets~1%7Bfileset%7D"
+
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}/files:
+ $ref:
"./filesets.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1filesets~1%7Bfileset%7D~1files"
+
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/topics:
$ref:
"./topics.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1topics"
diff --git
a/server/src/main/java/org/apache/gravitino/server/web/rest/FilesetOperations.java
b/server/src/main/java/org/apache/gravitino/server/web/rest/FilesetOperations.java
index 51baa3c655..2d4eb8ead7 100644
---
a/server/src/main/java/org/apache/gravitino/server/web/rest/FilesetOperations.java
+++
b/server/src/main/java/org/apache/gravitino/server/web/rest/FilesetOperations.java
@@ -199,8 +199,8 @@ public class FilesetOperations {
@PathParam("catalog") String catalog,
@PathParam("schema") String schema,
@PathParam("fileset") String fileset,
- @QueryParam("subPath") @DefaultValue("/") String subPath,
- @QueryParam("locationName") String locationName)
+ @QueryParam("sub_path") @DefaultValue("/") String subPath,
+ @QueryParam("location_name") String locationName)
throws UnsupportedEncodingException {
LOG.info(
"Received list files request: {}.{}.{}.{}, subPath: {},
locationName:{}",
