[OAS] Remove Elastic-Api-Version (#207071)

## Summary

We anticipate generating a single document per API version for the
foreseeable future. This PR updates our OAS document merging logic to
avoid adding the `Elastic-Api-Version` header to our spec.

This will also remove this header from current documentation.

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

oas_docs/overlays/alerting.overlays.yaml

@@ -7,10 +7,10 @@ actions:
   # Add some alerting API examples
   - target: "$.paths['/api/alerting/rule/{id}']['post']"
     description: "Add examples to create rule API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               createEsQueryEsqlRuleRequest:
                 $ref: "../examples/create_es_query_esql_rule_request.yaml"
@@ -25,7 +25,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 createEsQueryEsqlRuleResponse:
                   $ref: "../examples/create_es_query_esql_rule_response.yaml"
@@ -39,17 +39,17 @@ actions:
                   $ref: "../examples/create_tracking_containment_rule_response.yaml"
   - target: "$.paths['/api/alerting/rule/{id}']['put']"
     description: "Add examples to update rule API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31:
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               updateRuleRequest:
                 $ref: '../examples/update_rule_request.yaml'
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 updateRuleResponse:
                   $ref: '../examples/update_rule_response.yaml'
@@ -59,7 +59,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 findRulesResponse:
                   $ref: '../examples/find_rules_response.yaml'
@@ -77,10 +77,10 @@ actions:
   # Add some alerting rule parameters
   - target: "$.paths['/api/alerting/rule/{id}']['post']"
     description: "Add params to create rule API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31:
+    update:
+      requestBody:
+        content:
+          application/json:
             schema:
               properties:
                 params:
@@ -147,4 +147,3 @@ actions:
                     # Threshold rule (siem.thresholdRule)
                     # TLS certificate rule (xpack.uptime.alerts.tlsCertificate)
                     # Transform health (transform_health)
-  

oas_docs/overlays/connectors.overlays.yaml

@@ -12,10 +12,10 @@ actions:
   # Add some connector API examples
   - target: "$.paths['/api/actions/connector/{id}']['post']"
     description: "Add examples to create connector API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               createEmailConnectorRequest:
                 $ref: "../examples/create_email_connector_request.yaml"
@@ -28,7 +28,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 createEmailConnectorResponse:
                   $ref: "../examples/create_email_connector_response.yaml"
@@ -40,10 +40,10 @@ actions:
                   $ref: "../examples/get_connector_response.yaml"
   - target: "$.paths['/api/actions/connector/{id}/_execute']['post']"
     description: "Add examples to run connector API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               runIndexConnectorRequest:
                 $ref: "../examples/run_index_connector_request.yaml"
@@ -58,7 +58,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 runIndexConnectorResponse:
                   $ref: "../examples/run_index_connector_response.yaml"
@@ -78,7 +78,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 getConnectorResponse:
                   $ref: '../examples/get_connector_response.yaml'
@@ -89,7 +89,7 @@ actions:
         200:
           description: Indicates a successful call.
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 getConnectorTypesServerlessResponse:
                   $ref: '../examples/get_connector_types_generativeai_response.yaml'
@@ -100,16 +100,16 @@ actions:
         200:
           description: Indicates a successful call.
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 getConnectorsResponse:
                   $ref: '../examples/get_connectors_response.yaml'
   - target: "$.paths['/api/actions/connector/{id}']['put']"
     description: "Add examples to update connector API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31:
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               updateIndexConnectorRequest:
                 $ref: '../examples/update_index_connector_request.yaml'
@@ -129,10 +129,10 @@ actions:
   # Add some connector configuration schemas
   - target: "$.paths['/api/actions/connector/{id}']['post']"
     description: "Add config and secrets to create connector API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31:
+    update:
+      requestBody:
+        content:
+          application/json:
             schema:
               properties:
                 config:
@@ -246,10 +246,10 @@ actions:
                     - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/xmatters_secrets.yaml'
   - target: "$.paths['/api/actions/connector/{id}']['put']"
     description: "Add config and secrets to update connector API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31:
+    update:
+      requestBody:
+        content:
+          application/json:
             schema:
               properties:
                 config:
@@ -365,13 +365,13 @@ actions:
   - target: "$.paths['/api/actions/connector/{id}/_execute']['post'].requestBody.content.*.schema.properties.params"
     description: "Remove params in run connector API"
     remove: true
-  # Add some run connector params  
+  # Add some run connector params
   - target: "$.paths['/api/actions/connector/{id}/_execute']['post']"
     description: "Add examples to run connector API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             schema:
               properties:
                 params:

oas_docs/overlays/kibana.overlays.shared.yaml

@@ -7,39 +7,39 @@ actions:
 # Add some spaces API examples
   - target: "$.paths['/api/spaces/space']['post']"
     description: "Add example to create space API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               createSpaceRequest:
                 $ref: "../examples/create_space_request.yaml"
   - target: "$.paths['/api/spaces/space/{id}']['put']"
     description: "Add example to update space API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               updateSpaceRequest:
                 $ref: "../examples/update_space_request.yaml"
   - target: "$.paths['/api/spaces/space/{id}']['get']"
     description: "Add example to get space API"
-    update: 
+    update:
       responses:
-        200: 
-          content: 
-            application/json; Elastic-Api-Version=2023-10-31: 
+        200:
+          content:
+            application/json:
               examples:
                 getSpaceResponseExample:
                   $ref: "../examples/get_space_response.yaml"
   - target: "$.paths['/api/spaces/space']['get']"
     description: "Add example to get all spaces API"
-    update: 
+    update:
       responses:
-        200: 
-          content: 
-            application/json; Elastic-Api-Version=2023-10-31: 
+        200:
+          content:
+            application/json:
               examples:
                 getSpacesResponseExample1:
                   $ref: "../examples/get_spaces_response1.yaml"

oas_docs/overlays/kibana.overlays.yaml

@@ -41,7 +41,7 @@ actions:
     update:
       description: >
         Alerting enables you to define rules, which detect complex conditions within your data.
-        When a condition is met, the rule tracks it as an alert and runs the actions that are defined in the rule. 
+        When a condition is met, the rule tracks it as an alert and runs the actions that are defined in the rule.
         Actions typically involve the use of connectors to interact with Kibana services or third party integrations.
       externalDocs:
         description: Alerting documentation
@@ -109,19 +109,19 @@ actions:
 # Examples that are not applicable to serverless
   - target: "$.paths['/api/spaces/_copy_saved_objects']['post']"
     description: "Add example to copy saved objects to space API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               copySavedObjectsRequestExample1:
                 $ref: "../examples/copy_saved_objects_request1.yaml"
               copySavedObjectsRequestExample2:
                 $ref: "../examples/copy_saved_objects_request2.yaml"
       responses:
-        200: 
-          content: 
-            application/json; Elastic-Api-Version=2023-10-31: 
+        200:
+          content:
+            application/json:
               examples:
                 copySavedObjectsResponseExample1:
                   $ref: "../examples/copy_saved_objects_response1.yaml"
@@ -133,19 +133,19 @@ actions:
                   $ref: "../examples/copy_saved_objects_response4.yaml"
   - target: "$.paths['/api/spaces/_resolve_copy_saved_objects_errors']['post']"
     description: "Add example to resolve copy saved objects to space conflicts API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               resolveCopySavedObjectsRequestExample1:
                 $ref: "../examples/resolve_copy_saved_objects_request1.yaml"
               resolveCopySavedObjectsRequestExample2:
                 $ref: "../examples/resolve_copy_saved_objects_request2.yaml"
       responses:
-        200: 
-          content: 
-            application/json; Elastic-Api-Version=2023-10-31: 
+        200:
+          content:
+            application/json:
               examples:
                 resolveCopySavedObjectsResponseExample1:
                   $ref: "../examples/copy_saved_objects_response1.yaml"
@@ -153,35 +153,35 @@ actions:
                   $ref: "../examples/copy_saved_objects_response2.yaml"
   - target: "$.paths['/api/spaces/_disable_legacy_url_aliases']['post']"
     description: "Add example to disable legacy URL aliases API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               disableLegacyURLRequestExample1:
                 $ref: "../examples/disable_legacy_url_request1.yaml"
   - target: "$.paths['/api/spaces/_update_objects_spaces']['post']"
     description: "Add example to update saved object spaces API"
-    update: 
-      requestBody: 
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+    update:
+      requestBody:
+        content:
+          application/json:
             examples:
               updateObjectSpacesRequestExample1:
                 $ref: "../examples/update_saved_objects_spaces_request1.yaml"
       responses:
-        200: 
-          content: 
-            application/json; Elastic-Api-Version=2023-10-31: 
+        200:
+          content:
+            application/json:
               examples:
                 updateObjectSpacesResponseExample1:
                   $ref: "../examples/update_saved_objects_spaces_response1.yaml"
   - target: "$.paths['/api/security/role/{name}']['put']"
     description: "Add examples to create role API"
-    update: 
+    update:
       requestBody:
-        content: 
-          application/json; Elastic-Api-Version=2023-10-31: 
+        content:
+          application/json:
             examples:
               createRoleRequest1:
                 $ref: "../examples/create_role_request1.yaml"
@@ -197,7 +197,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 getRoleResponse1:
                   $ref: '../examples/get_role_response1.yaml'
@@ -207,7 +207,7 @@ actions:
       responses:
         200:
           content:
-            application/json; Elastic-Api-Version=2023-10-31:
+            application/json:
               examples:
                 getRolesResponse1:
                   $ref: '../examples/get_roles_response1.yaml'

packages/kbn-openapi-bundler/src/bundler/merge_documents/merge_documents.ts

@@ -17,7 +17,6 @@ import { mergeSecurityRequirements } from './merge_security_requirements';
 import { mergeTags } from './merge_tags';
 import { getOasVersion } from '../../utils/get_oas_version';
 import { getOasDocumentVersion } from '../../utils/get_oas_document_version';
-import { enrichWithVersionMimeParam } from './enrich_with_version_mime_param';
 import { MergeOptions } from './merge_options';
 
 interface MergeDocumentsOptions extends MergeOptions {
@@ -34,10 +33,6 @@ export async function mergeDocuments(
     : new Map([['', resolvedDocuments]]);
   const mergedByVersion = new Map<string, OpenAPIV3.Document>();
 
-  if (!options.splitDocumentsByVersion) {
-    enrichWithVersionMimeParam(resolvedDocuments);
-  }
-
   for (const [apiVersion, documentsGroup] of documentsByVersion.entries()) {
     validateSameOasVersion(documentsGroup);
 

packages/kbn-openapi-bundler/tests/merger/merge_multiple_specs.test.ts

@@ -70,7 +70,9 @@ describe('OpenAPI Merger - merge paths', () => {
     });
   });
 
-  it('merges different versions of the same endpoint', async () => {
+  // We do not expect to merge different versions of the same endpoint for the foreseeable future. This might change
+  // so keeping this test around for now.
+  it.skip('merges different versions of the same endpoint', async () => {
     const spec1 = createOASDocument({
       info: {
         version: '2023-10-31',

packages/kbn-openapi-bundler/tests/merger/merging_specs_with_conflicting_components.test.ts

@@ -86,7 +86,7 @@ describe('OpenAPI Merger - merging specs with conflicting components', () => {
 
     expect(mergedSpec.paths['/api/some_api']?.get?.responses['200']).toMatchObject({
       content: {
-        'application/json; Elastic-Api-Version=2023-10-31': {
+        'application/json': {
           schema: {
             $ref: '#/components/schemas/Spec1_SomeSchema',
           },
@@ -95,7 +95,7 @@ describe('OpenAPI Merger - merging specs with conflicting components', () => {
     });
     expect(mergedSpec.paths['/api/some_api']?.post?.responses['200']).toMatchObject({
       content: {
-        'application/json; Elastic-Api-Version=2023-10-31': {
+        'application/json': {
           schema: {
             $ref: '#/components/schemas/Spec2_SomeSchema',
           },
@@ -457,7 +457,7 @@ describe('OpenAPI Merger - merging specs with conflicting components', () => {
 
     expect(mergedSpec.paths['/api/some_api']?.post?.requestBody).toMatchObject({
       content: {
-        'application/json; Elastic-Api-Version=2023-10-31': {
+        'application/json': {
           encoding: {
             something: {
               headers: {
@@ -779,7 +779,7 @@ describe('OpenAPI Merger - merging specs with conflicting components', () => {
 
     expect(mergedSpec.paths['/api/some_api']?.get?.responses['200']).toMatchObject({
       content: {
-        'application/json; Elastic-Api-Version=2023-10-31': {
+        'application/json': {
           schema: expect.objectContaining({
             discriminator: expect.objectContaining({
               mapping: {