[8.15] [OAS][ML] Add sync API tags and description, minor OpenAPI fix…

…es (#189230) (#189320)

# Backport

This will backport the following commits from `main` to `8.15`:
- [[OAS][ML] Add sync API tags and description, minor OpenAPI fixes
(#189230)](#189230)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"lcawley@elastic.co"},"sourceCommit":{"committedDate":"2024-07-26T20:28:43Z","message":"[OAS][ML]
Add sync API tags and description, minor OpenAPI fixes
(#189230)","sha":"841e95c64b6fa29e680906140e356be43e73f75c","branchLabelMapping":{"^v8.16.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":[":ml","release_note:skip","docs","backport:prev-minor","Feature:OAS","v8.16.0"],"number":189230,"url":"https://github.com/elastic/kibana/pull/189230","mergeCommit":{"message":"[OAS][ML]
Add sync API tags and description, minor OpenAPI fixes
(#189230)","sha":"841e95c64b6fa29e680906140e356be43e73f75c"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v8.16.0","labelRegex":"^v8.16.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/189230","number":189230,"mergeCommit":{"message":"[OAS][ML]
Add sync API tags and description, minor OpenAPI fixes
(#189230)","sha":"841e95c64b6fa29e680906140e356be43e73f75c"}}]}]
BACKPORT-->

oas_docs/output/kibana.yaml

@@ -1401,43 +1401,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Machine_learning_APIs_mlSync4xxResponse'
-      security:
-        - Machine_learning_APIs_basicAuth: []
-        - Machine_learning_APIs_apiKeyAuth: []
-  /s/{spaceId}/api/ml/saved_objects/sync:
-    get:
-      summary: Sync saved objects
-      description: >
-        Synchronizes Kibana saved objects for machine learning jobs and trained
-        models. You must have `all` privileges for the **Machine Learning**
-        feature in the **Analytics** section of the Kibana feature privileges.
-        This API runs automatically when you start Kibana and periodically
-        thereafter.
-      operationId: mlSyncWithSpaceId
-      tags:
-        - ml
-      parameters:
-        - $ref: '#/components/parameters/Machine_learning_APIs_spaceParam'
-        - $ref: '#/components/parameters/Machine_learning_APIs_simulateParam'
-      responses:
-        '200':
-          description: Indicates a successful call
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Machine_learning_APIs_mlSync200Response'
-              examples:
-                syncExample:
-                  $ref: '#/components/examples/Machine_learning_APIs_mlSyncExample'
-        '401':
-          description: Authorization information is missing or invalid.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Machine_learning_APIs_mlSync4xxResponse'
-      security:
-        - Machine_learning_APIs_basicAuth: []
-        - Machine_learning_APIs_apiKeyAuth: []
   /api/encrypted_saved_objects/_rotate_key:
     post:
       summary: Rotate a key for encrypted saved objects
@@ -3123,15 +3086,6 @@ components:
       schema:
         type: string
         example: hour_of_day
-    Machine_learning_APIs_spaceParam:
-      in: path
-      name: spaceId
-      description: >-
-        An identifier for the space. If `/s/` and the identifier are omitted
-        from the path, the default space is used.
-      required: true
-      schema:
-        type: string
     Machine_learning_APIs_simulateParam:
       in: query
       name: simulate
@@ -11374,13 +11328,6 @@ components:
           schema:
             $ref: '#/components/schemas/Connectors_action_response_properties'
   securitySchemes:
-    Machine_learning_APIs_basicAuth:
-      type: http
-      scheme: basic
-    Machine_learning_APIs_apiKeyAuth:
-      type: apiKey
-      in: header
-      name: ApiKey
     Saved_objects_basicAuth:
       type: http
       scheme: basic

x-pack/plugins/ml/common/openapi/README.md

@@ -4,17 +4,4 @@ The current self-contained spec file can be used for online tools like those fou
 
 A guide about the openApi specification can be found at [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/).
 
-The `ml_apis_v3.yaml` file uses OpenAPI Specification Version 3.0.1.
-
- ## Tools
-
-It is possible to validate the docs before bundling them by running these
-commands in the `x-pack/plugins/ml/common/openapi/` folder:
-
-```
-npx swagger-cli validate ml_apis.yaml
-npx @redocly/cli lint ml_apis.yaml
-
-npx swagger-cli validate ml_apis_serverless.yaml
-npx @redocly/cli lint ml_apis_serverless.yaml
-```
+These files are joined with the rest of the Kibana APIs per `oas_docs/README.md`

x-pack/plugins/ml/common/openapi/ml_apis.yaml

@@ -41,44 +41,44 @@ paths:
               schema:
                 $ref: '#/components/schemas/mlSync4xxResponse'
 
-  /s/{spaceId}/api/ml/saved_objects/sync:
-    get:
-      summary: Sync saved objects
-      description: >
-        Synchronizes Kibana saved objects for machine learning jobs and trained models.
-        You must have `all` privileges for the **Machine Learning** feature in the **Analytics** section of the Kibana feature privileges.
-        This API runs automatically when you start Kibana and periodically thereafter.
-      operationId: mlSyncWithSpaceId
-      tags:
-        - ml
-      parameters:
-        - $ref: '#/components/parameters/spaceParam'
-        - $ref: '#/components/parameters/simulateParam'
-      responses:
-        '200':
-          description: Indicates a successful call
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/mlSync200Response'
-              examples:
-                syncExample:
-                  $ref: '#/components/examples/mlSyncExample'
-        '401':
-          description: Authorization information is missing or invalid.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/mlSync4xxResponse'
+  # /s/{spaceId}/api/ml/saved_objects/sync:
+    # get:
+    #   summary: Sync saved objects
+    #   description: >
+    #     Synchronizes Kibana saved objects for machine learning jobs and trained models.
+    #     You must have `all` privileges for the **Machine Learning** feature in the **Analytics** section of the Kibana feature privileges.
+    #     This API runs automatically when you start Kibana and periodically thereafter.
+    #   operationId: mlSyncWithSpaceId
+    #   tags:
+    #     - ml
+    #   parameters:
+    #     - $ref: '#/components/parameters/spaceParam'
+    #     - $ref: '#/components/parameters/simulateParam'
+    #   responses:
+    #     '200':
+    #       description: Indicates a successful call
+    #       content:
+    #         application/json:
+    #           schema:
+    #             $ref: '#/components/schemas/mlSync200Response'
+    #           examples:
+    #             syncExample:
+    #               $ref: '#/components/examples/mlSyncExample'
+    #     '401':
+    #       description: Authorization information is missing or invalid.
+    #       content:
+    #         application/json:
+    #           schema:
+    #             $ref: '#/components/schemas/mlSync4xxResponse'
 components:
  parameters:
-  spaceParam:
-    in: path
-    name: spaceId
-    description: An identifier for the space. If `/s/` and the identifier are omitted from the path, the default space is used.
-    required: true
-    schema:
-      type: string
+  # spaceParam:
+  #   in: path
+  #   name: spaceId
+  #   description: An identifier for the space. If `/s/` and the identifier are omitted from the path, the default space is used.
+  #   required: true
+  #   schema:
+  #     type: string
   simulateParam:
     in: query
     name: simulate
@@ -87,14 +87,6 @@ components:
     schema:
       type: boolean
     example: 'true'
- securitySchemes:
-  basicAuth:
-    type: http
-    scheme: basic
-  apiKeyAuth:
-    type: apiKey
-    in: header
-    name: ApiKey
  schemas:
     mlSyncResponseSuccess:
       type: boolean
@@ -212,6 +204,3 @@ components:
           "datafeedsAdded": {},
           "datafeedsRemoved": {}
         }
-security:
-  - basicAuth: [ ]
-  - apiKeyAuth: [ ]

x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml

@@ -49,11 +49,6 @@ components:
     schema:
       type: boolean
     example: 'true'
- securitySchemes:
-  apiKeyAuth:
-    type: apiKey
-    in: header
-    name: ApiKey
  schemas:
     mlSyncResponseSuccess:
       type: boolean
@@ -171,5 +166,3 @@ components:
           "datafeedsAdded": {},
           "datafeedsRemoved": {}
         }
-security:
-  - apiKeyAuth: [ ]

x-pack/plugins/ml/server/routes/saved_objects.ts

@@ -84,8 +84,11 @@ export function savedObjectsRoutes(
           'access:ml:canCreateJob',
           'access:ml:canCreateDataFrameAnalytics',
           'access:ml:canCreateTrainedModels',
+          'oas-tag:machine learning',
         ],
       },
+      description:
+        'Synchronizes Kibana saved objects for machine learning jobs and trained models. This API runs automatically when you start Kibana and periodically thereafter.',
     })
     .addVersion(
       {