oas: [14/14] improve admin oas (#8989)

www/utils/generated/oas-output/operations/admin/post_admin_stock-locations_[id]_sales-channels.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/stock-locations/{id}/sales-channels
  * operationId: PostStockLocationsIdSalesChannels
- * summary: Add Sales Channels to Stock Location
+ * summary: Manage Sales Channels of a Stock Location
- * description: Add a list of sales channels to a stock location.
+ * x-sidebar-summary: Manage Sales Channels
+ * description: Manage the sales channels in a stock location by adding or removing them.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -62,22 +63,22 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The sales channels to add or remove.
  *         properties:
  *           add:
  *             type: array
- *             description: The stock location's add.
+ *             description: The sales channels to add.
  *             items:
  *               type: string
  *               title: add
- *               description: The add's details.
+ *               description: A sales channel's ID.
  *           remove:
  *             type: array
- *             description: The stock location's remove.
+ *             description: The sales channels to remove.
  *             items:
  *               type: string
  *               title: remove
- *               description: The remove's details.
+ *               description: A sales channel's ID.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_admin_tax-rates_[id]_rules.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/tax-rates/{id}/rules
  * operationId: PostTaxRatesIdRules
- * summary: Add Rules to Tax Rate
+ * summary: Create Tax Rule for a Rate
- * description: Add a list of rules to a tax rate.
+ * x-sidebar-summary: Create Tax Rule
+ * description: Create a tax rule for a rate.
  * x-authenticated: true
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_uploads.ts

@@ -1,8 +1,8 @@
 /**
  * @oas [post] /admin/uploads
  * operationId: PostUploads
- * summary: Create Upload
+ * summary: Upload Files
- * description: Create a upload.
+ * description: Upload files to the configured File Module Provider.
  * x-authenticated: true
  * parameters: []
  * security:
@@ -15,17 +15,17 @@
  *       schema:
  *         oneOf:
  *           - type: object
- *             description: SUMMARY
+ *             description: The files to upload.
  *             required:
  *               - files
  *             properties:
  *               files:
  *                 type: array
- *                 description: The upload's files.
+ *                 description: The files to upload.
  *                 items:
  *                   oneOf:
  *                     - type: object
- *                       description: The file's files.
+ *                       description: A file's details.
  *                       required:
  *                         - name
  *                         - content
@@ -37,10 +37,10 @@
  *                         content:
  *                           type: string
  *                           title: content
- *                           description: The file's content.
+ *                           description: The file's base64 content.
  *                     - $ref: "#/components/schemas/File"
  *           - $ref: "#/components/schemas/FileList"
- *         description: SUMMARY
+ *         description: The files to upload.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_admin_workflows-executions_[workflow_id]_run.ts

@@ -1,13 +1,13 @@
 /**
  * @oas [post] /admin/workflows-executions/{workflow_id}/run
  * operationId: PostWorkflowsExecutionsWorkflow_idRun
- * summary: Add Runs to Workflows Execution
+ * summary: Execute a Workflow
- * description: Add a list of runs to a workflows execution.
+ * description: Execute a workflow by its ID.
  * x-authenticated: true
  * parameters:
  *   - name: workflow_id
  *     in: path
- *     description: The workflows execution's workflow id.
+ *     description: The workflow's ID.
  *     required: true
  *     schema:
  *       type: string
@@ -35,11 +35,24 @@
  *       application/json:
  *         schema:
  *           type: object
- *           description: SUMMARY
+ *           description: The execution's details.
  *           required:
  *             - acknowledgement
  *           properties:
- *             acknowledgement: {}
+ *             acknowledgement:
+ *               type: object
+ *               description: The workflow's details
+ *               required:
+ *                 - workflowId
+ *                 - transactionId
+ *               properties:
+ *                 workflowId:
+ *                   type: string
+ *                   description: The ID of the executed workflow.
+ *                   name: workflowId
+ *                 transactionId:
+ *                   type: string
+ *                   description: The ID of the workflow exection's transaction. Use this later to track the workflow execution's progress or succeed / fail its steps.
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

www/utils/generated/oas-output/operations/admin/post_admin_workflows-executions_[workflow_id]_steps_failure.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/workflows-executions/{workflow_id}/steps/failure
  * operationId: PostWorkflowsExecutionsWorkflow_idStepsFailure
- * summary: Add Failures to Workflows Execution
+ * summary: Fail a Step in a Workflow's Execution
- * description: Add a list of failures to a workflows execution.
+ * x-sidebar-summary: Fail a Step
+ * description: Set the status of a step in a workflow's execution as failed. This is useful for long-running workflows.
  * x-authenticated: true
  * parameters:
  *   - name: workflow_id
@@ -40,14 +41,14 @@
  *       application/json:
  *         schema:
  *           type: object
- *           description: SUMMARY
+ *           description: The details of failing the workflow step.
  *           required:
  *             - success
  *           properties:
  *             success:
  *               type: boolean
  *               title: success
- *               description: The workflows execution's success.
+ *               description: Whether the workflow step has failed successfully.
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

www/utils/generated/oas-output/operations/admin/post_admin_workflows-executions_[workflow_id]_steps_success.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/workflows-executions/{workflow_id}/steps/success
  * operationId: PostWorkflowsExecutionsWorkflow_idStepsSuccess
- * summary: Add Successes to Workflows Execution
+ * summary: Succeed a Step in a Workflow's Execution
- * description: Add a list of successes to a workflows execution.
+ * x-sidebar-summary: Succed a Step
+ * description: Set the status of a step in a workflow's execution as successful. This is useful for long-running workflows.
  * x-authenticated: true
  * parameters:
  *   - name: workflow_id
@@ -40,14 +41,14 @@
  *       application/json:
  *         schema:
  *           type: object
- *           description: SUMMARY
+ *           description: The details of succeeding the workflow step.
  *           required:
  *             - success
  *           properties:
  *             success:
  *               type: boolean
  *               title: success
- *               description: The workflows execution's success.
+ *               description: Whether the workflow step was succeeded.
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":