From 580b6225c2f2d4f8bb9074ee6f721b5a6d950311 Mon Sep 17 00:00:00 2001 From: Peidian li <38486782+coolderli@users.noreply.github.com> Date: Fri, 1 Mar 2024 11:28:28 +0800 Subject: [PATCH] [#2367] improvement(fileset): Add open API doc for fileset catalog (#2403) ### What changes were proposed in this pull request? - close #2367 ### Why are the changes needed? - Fix: #2367 ### Does this PR introduce _any_ user-facing change? - no ### How was this patch tested? - `./gradlew build` --------- Co-authored-by: mchades --- docs/open-api/filesets.yaml | 393 ++++++++++++++++++++++++++++++++++++ docs/open-api/openapi.yaml | 14 ++ 2 files changed, 407 insertions(+) create mode 100644 docs/open-api/filesets.yaml diff --git a/docs/open-api/filesets.yaml b/docs/open-api/filesets.yaml new file mode 100644 index 00000000000..b163a6a4d51 --- /dev/null +++ b/docs/open-api/filesets.yaml @@ -0,0 +1,393 @@ +# +# Copyright 2024 Datastrato Pvt Ltd. +# This software is licensed under the Apache License version 2. +# + +--- + +paths: + + /metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets: + parameters: + - $ref: "./openapi.yaml#/components/parameters/metalake" + - $ref: "./openapi.yaml#/components/parameters/catalog" + - $ref: "./openapi.yaml#/components/parameters/schema" + + get: + tags: + - fileset + summary: List filesets + operationId: listFilesets + responses: + "200": + $ref: "./openapi.yaml#/components/responses/EntityListResponse" + "400": + $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse" + "5xx": + $ref: "./openapi.yaml#/components/responses/ServerErrorResponse" + + post: + tags: + - fileset + summary: Create fileset + operationId: createFileset + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/FilesetCreateRequest" + examples: + FilesetCreateRequest: + $ref: "#/components/examples/FilesetCreateRequest" + responses: + "200": + $ref: "#/components/responses/FilesetResponse" + "409": + description: Conflict - The target fileset already exists + content: + application/vnd.gravitino.v1+json: + schema: + $ref: "./openapi.yaml#/components/schemas/ErrorModel" + examples: + FilesetAlreadyExistsErrorResponse: + $ref: "#/components/examples/FilesetAlreadyExistsException" + "5xx": + $ref: "./openapi.yaml#/components/responses/ServerErrorResponse" + + + /metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}: + 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: Get fileset + operationId: loadFileset + description: Returns the specified fileset object + responses: + "200": + $ref: "#/components/responses/FilesetResponse" + "404": + description: Not Found - The target fileset 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" + + put: + tags: + - fileset + summary: Update fileset + operationId: alterFileset + description: Updates the specified fileset in a schema + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/FilesetUpdatesRequest" + responses: + "200": + $ref: "#/components/responses/FilesetResponse" + "400": + $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse" + "404": + description: Not Found - The target fileset 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" + "409": + description: Conflict - The target fileset already exists + content: + application/vnd.gravitino.v1+json: + schema: + $ref: "./openapi.yaml#/components/schemas/ErrorModel" + examples: + FilesetAlreadyExistsErrorResponse: + $ref: "#/components/examples/FilesetAlreadyExistsException" + "5xx": + $ref: "./openapi.yaml#/components/responses/ServerErrorResponse" + + delete: + tags: + - fileset + summary: Drop fileset + operationId: dropFileset + responses: + "200": + $ref: "./openapi.yaml#/components/responses/DropResponse" + "400": + $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse" + "5xx": + $ref: "./openapi.yaml#/components/responses/ServerErrorResponse" + + +components: + + schemas: + Fileset: + type: object + required: + - name + properties: + name: + type: string + description: The name of the fileset + description: + type: string + description: The description of the fileset + nullable: true + type: + type: string + description: The type of the fileset + nullable: true + comment: + type: string + description: The comment of the fileset + nullable: true + storageLocation: + type: string + description: The location of the fileset + nullable: true + properties: + type: object + description: The properties of the fileset + nullable: true + default: {} + additionalProperties: + type: string + FilesetCreateRequest: + type: object + required: + - name + properties: + name: + type: string + description: The name of the fileset + description: + type: string + description: The description of the fileset + nullable: true + type: + type: string + description: The type of the fileset + nullable: true + comment: + type: string + description: The comment of the fileset + nullable: true + storageLocation: + type: string + description: The location of the fileset + nullable: true + properties: + type: object + description: The properties of the fileset + nullable: true + default: {} + additionalProperties: + type: string + + FilesetUpdatesRequest: + type: object + required: + - name + properties: + updates: + type: array + items: + $ref: "#/components/schemas/FilesetUpdateRequest" + + FilesetUpdateRequest: + oneOf: + - $ref: "#/components/schemas/RenameFilesetRequest" + - $ref: "#/components/schemas/SetFilesetPropertiesRequest" + - $ref: "#/components/schemas/UpdateFilesetCommentRequest" + - $ref: "#/components/schemas/RemoveFilesetPropertiesRequest" + discriminator: + propertyName: "@type" + mapping: + rename: "#/components/schemas/RenameFilesetRequest" + setProperties: "#/components/schemas/SetFilesetPropertiesRequest" + updateComment: "#/components/schemas/UpdateFilesetCommentRequest" + removeProperties: "#/components/schemas/RemoveFilesetPropertiesRequest" + + RenameFilesetRequest: + type: object + required: + - "@type" + - newName + properties: + "@type": + type: string + description: The type of the update + enum: + - rename + newName: + type: string + description: The new name of the fileset + example: { + "@type": "rename", + "newName": "newName" + } + + SetFilesetPropertiesRequest: + type: object + required: + - "@type" + - property + - value + properties: + "@type": + type: string + description: The type of the update + enum: + - setProperty + property: + type: string + description: The name of the property to set + value: + type: string + description: The value of the property to set + example: { + "@type": "setProperty", + "property": "key", + "value": "value" + } + + UpdateFilesetCommentRequest: + type: object + required: + - "@type" + - newComment + properties: + "@type": + type: string + description: The type of the update + enum: + - updateComment + newComment: + type: string + description: The new comment of the fileset + example: { + "@type": "updateComment", + "newComment": "new comment" + } + + RemoveFilesetPropertiesRequest: + type: object + required: + - "@type" + - property + properties: + "@type": + type: string + description: The type of the update + enum: + - removeProperty + property: + type: string + description: The property to remove + example: { + "@type": "removeProperty", + "property": "key1" + } + + responses: + FilesetResponse: + description: The response of fileset object + content: + application/vnd.gravitino.v1+json: + schema: + type: object + properties: + code: + type: integer + format: int32 + description: Status code of the response + enum: + - 0 + fileset: + $ref: "#/components/schemas/Fileset" + examples: + FilesetResponse: + $ref: "#/components/examples/FilesetResponse" + + + examples: + FilesetCreateRequest: + value: { + "name": "fileset1", + "description": "This is a fileset", + "type": "managed", + "comment": "This is a comment", + "storageLocation": "s3://bucket/path", + "properties": { + "key1": "value1", + "key2": "value2" + } + } + + FilesetResponse: + value: { + "code": 0, + "fileset" : { + "name": "fileset1", + "description": "This is a fileset", + "type": "managed", + "comment": "This is a comment", + "storageLocation": "s3://bucket/path", + "properties": { + "key1": "value1", + "key2": "value2" + } + } + } + + FilesetAlreadyExistsException: + value: { + "code": 1001, + "type": "FilesetAlreadyExistsException", + "message": "Fileset already exists", + "stack": [ + "java.lang.FilesetAlreadyExistsException: Fileset already exists" + ] + } + + NoSuchFilesetException: + value: { + "code": 1004, + "type": "NoSuchFilesetException", + "message": "Fileset does not exist", + "stack": [ + "java.lang.NoSuchFilesetException: Fileset does not exist" + ] + } + + + + diff --git a/docs/open-api/openapi.yaml b/docs/open-api/openapi.yaml index 17816cb3932..02f7a191e46 100644 --- a/docs/open-api/openapi.yaml +++ b/docs/open-api/openapi.yaml @@ -68,6 +68,12 @@ paths: /metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/tables/{table}/partitions/{partition}: $ref: "./partitions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1tables~1%7Btable%7D~1partitions~1%7Bpartition%7D" + /metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets: + $ref: "./filesets.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1filesets" + + /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" + components: schemas: @@ -246,6 +252,14 @@ components: schema: type: string + fileset: + name: fileset + in: path + description: The name of the fileset + required: true + schema: + type: string + securitySchemes: OAuth2WithJWT: