apply pr reviews

Author: Leopold-Cramer

dataset/src/main/openapi/dataset.yaml

@@ -24,7 +24,7 @@ paths:
       operationId: createDataset
       tags:
         - dataset
-      description: "Create a new dataset in the workspace. Required fields: name. The dataset is initialized with empty data and can be populated through dataset parts. Creator becomes admin."
+      description: "Create a new dataset in the workspace. The dataset is initialized with empty data and can be populated through dataset parts."
       summary: Create a Dataset
       requestBody:
         content:
@@ -235,7 +235,7 @@ paths:
       operationId: deleteDataset
       tags:
         - dataset
-      description: "Permanently delete a dataset and all its data parts. This operation cannot be undone. Returns 204 on success, 404 if not found, 409 if dataset is in use by runners."
+      description: "Permanently delete a dataset and all its data parts. This operation cannot be undone."
       summary: Delete a Dataset
       responses:
         "204":
@@ -461,7 +461,7 @@ paths:
       operationId: createDatasetPart
       tags:
         - dataset
-      description: "Create a new data part within a dataset. Specify type as 'FILE' for file uploads or 'DB' for database queries. Returns the created part with generated ID."
+      description: "Create a new data part within a dataset. Specify type as 'File' for file uploads or 'DB' for database queries. Returns the created part with generated ID."
       summary: Create a data part of a Dataset
       requestBody:
         content:
@@ -508,7 +508,7 @@ paths:
         - $ref: '#/components/parameters/size'
       tags:
         - dataset
-      description: "Retrieve all data parts associated with a dataset. Parts can be of type FILE (uploaded files) or DB (database connections). Returns part metadata, type, and status."
+      description: "Retrieve all data parts associated with a dataset. Parts can be of type File (uploaded files) or DB (database connections). Returns part metadata, type, and status."
       summary: Retrieve all dataset parts of a Dataset
       responses:
         "200":
@@ -761,7 +761,7 @@ paths:
       operationId: queryData
       tags:
         - dataset
-      description: "Execute a SQL or DSL query against a database-type dataset part. The query parameter is required. Results are returned as JSON. Only available for parts with type=DB."
+      description: "Execute a SQL or DSL query against a database-type dataset part. The query parameter is required. Results are returned as plain-text CSV. Only available for parts with type=DB."
       summary: |
         Query data of a Dataset part.
         This endpoint is only available for dataset parts that support queries (type == DB).

meta/src/main/openapi/meta.yaml

@@ -17,7 +17,7 @@ paths:
       operationId: about
       tags:
         - meta
-      description: "Retrieve API version information, build details, and platform configuration. Useful for debugging and compatibility checks."
+      description: "Retrieve API version information and build details."
       summary: Get various information about the API
       responses:
         "200":

organization/src/main/openapi/organization.yaml

@@ -18,7 +18,7 @@ paths:
       operationId: createOrganization
       tags:
         - organization
-      description: "Create a new organization. Required: name. Optional: security configuration. The creating user automatically becomes an administrator."
+      description: "Create a new organization."
       summary: Create a new organization
       requestBody:
         required: true
@@ -155,7 +155,7 @@ paths:
       operationId: deleteOrganization
       tags:
         - organization
-      description: "Permanently delete an organization. Requires all workspaces within the organization to be deleted first. This operation cannot be undone."
+      description: "Permanently delete an organization. This operation cannot be undone."
       summary: Delete an organization
       responses:
         "204":
@@ -302,7 +302,7 @@ paths:
       operationId: createOrganizationAccessControl
       tags:
         - organization
-      description: "Grant access to an organization for a user or group. Valid roles: viewer, editor, admin."
+      description: "Grant access to an organization for a user or group."
       summary: Add a control access to the Organization
       requestBody:
         description: The new Organization security access to add.

runner/src/main/openapi/runner.yaml

@@ -20,7 +20,7 @@ paths:
       operationId: createRunner
       tags:
         - runner
-      description: "Create a new runner for executing simulations. Required: name, solutionId, runTemplateId. Use parentId to create a child runner that inherits configuration from a parent."
+      description: "Create a new runner for executing simulations. Use parentId to create a child runner that inherits configuration from a parent."
       summary: Create a new Runner
       requestBody:
         description: the Runner to create

solution/src/main/openapi/solution.yaml

@@ -20,7 +20,7 @@ paths:
       operationId: createSolution
       tags:
         - solution
-      description: "Create a new solution with optional run templates and parameter definitions. Required: key (unique identifier), name. The solution key must be unique within the organization."
+      description: "Create a new solution with optional run templates and parameter definitions."
       summary: Create a new solution
       requestBody:
         description: The Solution to create
@@ -745,7 +745,7 @@ paths:
       operationId: createSolutionAccessControl
       tags:
         - solution
-      description: "Grant access to a dataset for a user or group. Required: identity id and role. Valid roles: viewer, editor, admin. Returns 400 if user already has access."
+      description: "Grant access to a dataset for a user or group."
       summary: Create solution access control
       requestBody:
         description: Access control to create

workspace/src/main/openapi/workspace.yaml

@@ -19,7 +19,7 @@ paths:
       operationId: createWorkspace
       tags:
         - workspace
-      description: "Create a new workspace linked to a solution. Required: key (unique identifier), name, and solution configuration. The workspace key must be unique within the organization."
+      description: "Create a new workspace linked to a solution."
       summary: Create a new workspace
       requestBody:
         description: The Workspace to create
@@ -157,7 +157,7 @@ paths:
       operationId: deleteWorkspace
       tags:
         - workspace
-      description: "Permanently delete a workspace. All datasets and runners within the workspace must be deleted first. This operation cannot be undone."
+      description: "Permanently delete a workspace."
       summary: Delete a workspace
       responses:
         "204":
@@ -175,7 +175,7 @@ paths:
       operationId: createWorkspaceFile
       tags:
         - workspace
-      description: "Upload a file to workspace storage. Use 'destination' to specify path, 'overwrite' to replace existing files. Returns 400 if file exists and overwrite is false."
+      description: "Upload a file to workspace storage. Use 'destination' to specify path, 'overwrite' to replace existing files."
       summary: Upload a file for the Workspace
       requestBody:
         description: The file to upload
@@ -280,7 +280,7 @@ paths:
       operationId: getWorkspaceFile
       tags:
         - workspace
-      description: "Download a specific file from workspace storage. Requires 'file_name' query parameter. Returns file as binary stream. Returns error if file doesn't exist."
+      description: "Download a specific file from workspace storage. Returns file as binary stream."
       summary: Download the Workspace File specified
       responses:
         "200":
@@ -428,7 +428,7 @@ paths:
       operationId: createWorkspaceAccessControl
       tags:
         - workspace
-      description: "Grant access to a workspace for a user or group. Valid roles: viewer, editor, admin. Returns 400 if user already has access."
+      description: "Grant access to a workspace for a user or group."
       summary: Add a control access to the Workspace
       requestBody:
         description: The new Workspace security access to add.