[HTTP/OAS] Merge OpenAPI specs by using kbn-openapi-bundler

.buildkite/scripts/steps/checks.sh

@@ -15,3 +15,4 @@ fi
 .buildkite/scripts/steps/code_generation/security_solution_codegen.sh
 .buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh
 .buildkite/scripts/steps/code_generation/osquery_codegen.sh
+.buildkite/scripts/steps/openapi_bundling/final_merge.sh

.buildkite/scripts/steps/openapi_bundling/final_merge.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+source .buildkite/scripts/common/util.sh
+
+echo --- Merge Kibana OpenAPI specs
+
+(cd oas_docs && make api-docs && make api-docs-lint)

oas_docs/.spectral.yaml

@@ -1,6 +1,6 @@
-extends: ["spectral:oas"]
+extends: ['spectral:oas']
 rules:
-# Built-in rules
+  # Built-in rules
   # Descriptions
   oas3-parameter-description: warn
   oas2-parameter-description: warn
@@ -13,10 +13,10 @@ rules:
   oas3-valid-media-example: false
   oas3-valid-schema-example: false
   oas2-valid-media-example: false
-  # Operations 
-  operation-operationId: warn
-  operation-operationId-unique: warn
-  operation-operationId-valid-in-url: warn
+  # Operations
+  operation-operationId: error
+  operation-operationId-unique: error
+  operation-operationId-valid-in-url: error
   operation-tag-defined: warn
   operation-tags: warn
   # Responses
@@ -25,28 +25,30 @@ rules:
   oas3-schema: error
   oas2-schema: error
   array-items: false
+  # Bump.sh handles $ref siblings. Documentation wise it's convenient to have properties like descriptions next to $ref.
+  no-$ref-siblings: off
   # Tags
   openapi-tags: warn
   openapi-tags-alphabetical: info
   # Turn off some built-in rules
   operation-description: false
   operation-singular-tag: false
-# Custom rules
+  # Custom rules
   # Descriptions
   avoid-problematic-words:
     description: Ban certain words from descriptions
-    message: "Use appropriate replacements for problematic terms"
+    message: 'Use appropriate replacements for problematic terms'
     severity: warn
-    given: "$..*.description"
+    given: '$..*.description'
     then:
       function: pattern
       functionOptions:
         notMatch: /(blacklist|whitelist|execute|kill)/i
   # Examples
   operation-success-examples:
-    formats: ["oas3_1"]
+    formats: ['oas3_1']
     description: Response code 200 should have at least one example.
-    message: "Each response body should have a realistic example. It must not contain any sensitive or confidential data."
+    message: 'Each response body should have a realistic example. It must not contain any sensitive or confidential data.'
     severity: info
     given: $.paths[*][*].responses.[200].content.[application/json]
     then:
@@ -55,7 +57,7 @@ rules:
   # Extensions
   internal-extension:
     description: Operations should not have x-internal extension.
-    message: "Do not publish x-internal operations"
+    message: 'Do not publish x-internal operations'
     severity: error
     given: $.paths[*][*]
     then:
@@ -64,16 +66,16 @@ rules:
   # Operations
   operation-summary:
     description: Operations should have summaries.
-    message: "Each operation should have a summary"
+    message: 'Each operation should have a summary'
     severity: error
     recommended: true
     given: $.paths[*][*]
     then:
       field: summary
-      function: defined   
+      function: defined
   operation-summary-length:
     description: Operation summary should be between 5 and 45 characters
-    given: "$.paths[*][*]"
+    given: '$.paths[*][*]'
     then:
       field: summary
       function: length
@@ -83,14 +85,14 @@ rules:
     severity: warn
   simple-verbs-in-summary:
     given:
-      - "$.paths[*][*].summary"
+      - '$.paths[*][*].summary'
     then:
       function: pattern
       functionOptions:
-        notMatch: "Retrieve|Return|List *"
+        notMatch: 'Retrieve|Return|List *'
     severity: warn
     description: Summaries should use common verbs.
-    message: "Summaries should use common verbs like Get, Update, Delete whenever possible"
+    message: 'Summaries should use common verbs like Get, Update, Delete whenever possible'
   # NOTE: This one hiccups on acronyms so perhaps too noisy
   # docs-operation-summary-sentence-case:
   #   description: Operation summary should be sentence cased
@@ -101,4 +103,3 @@ rules:
   #     functionOptions:
   #       match: /^[A-Z]+[^A-Z]+$/
   #   severity: warn
-

oas_docs/kibana.info.yaml

@@ -7,15 +7,15 @@ info:
     Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
     request.
     API requests return JSON output, which is a format that is machine-readable and works well for automation.
-    
+
     To interact with Kibana APIs, use the following operations:
-    
+
     - GET: Fetches the information.
     - PATCH: Applies partial modifications to the existing information.
     - POST: Adds new information.
     - PUT: Updates the existing information.
     - DELETE: Removes the information.
-    
+
     You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
     For example:
 
@@ -24,26 +24,26 @@ info:
     ```
 
     For more information about the console, refer to [Run API requests](https://www.elastic.co/guide/en/kibana/current/console-kibana.html).
-  version: "1.0.2"
+  version: '1.0.2'
   license:
     name: Elastic License 2.0
     url: https://www.elastic.co/licensing/elastic-license
-  contact: 
+  contact:
     name: Kibana Team
-# servers:
-#   - url: https://{kibana_url}
-#     variables:
-#       kibana_url:
-#         default: localhost:5601
-# security:
-#   - apiKeyAuth: []
-# components:
-#   securitySchemes:
-#     apiKeyAuth:
-#       type: apiKey
-#       in: header
-#       name: Authorization
-#       description: >
-#         These APIs use key-based authentication.
-#         You must create an API key and use the encoded value in the request header.
-#         For example: `Authorization: ApiKey base64AccessApiKey`
+servers:
+  - url: https://{kibana_url}
+    variables:
+      kibana_url:
+        default: localhost:5601
+security:
+  - apiKeyAuth: []
+components:
+  securitySchemes:
+    apiKeyAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: >
+        These APIs use key-based authentication.
+        You must create an API key and use the encoded value in the request header.
+        For example: `Authorization: ApiKey base64AccessApiKey`

oas_docs/makefile

@@ -14,7 +14,12 @@
 # permission is obtained from Elasticsearch B.V.
 
 .PHONY: api-docs
-api-docs: ## Generate kibana.serverless.yaml and kibana.yaml
+api-docs: ## Generate Serverless and ESS Kibana OpenAPI bundles with kbn-openapi-bundler
+	@node scripts/merge_serverless_oas.js
+	@node scripts/merge_ess_oas.js
+
+.PHONY: api-docs-redocly
+api-docs-redocly: ## Generate kibana.serverless.yaml and kibana.yaml with Redocly CLI
 	@npx @redocly/cli join "kibana.info.serverless.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml" "../x-pack/plugins/actions/docs/openapi/bundled_serverless.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis_serverless.yaml" "../packages/core/saved-objects/docs/openapi/bundled_serverless.yaml" "../x-pack/plugins/observability_solution/slo/docs/openapi/slo/bundled.yaml"  "bundle.serverless.json" -o "output/kibana.serverless.yaml" --prefix-components-with-info-prop title
 	@npx @redocly/cli join "kibana.info.yaml" "../x-pack/plugins/alerting/docs/openapi/bundled.yaml" "../x-pack/plugins/observability_solution/apm/docs/openapi/apm.yaml"  "../x-pack/plugins/cases/docs/openapi/bundled.yaml" "../x-pack/plugins/actions/docs/openapi/bundled.yaml" "../src/plugins/data_views/docs/openapi/bundled.yaml" "../x-pack/plugins/ml/common/openapi/ml_apis.yaml" "../packages/core/saved-objects/docs/openapi/bundled.yaml"  "bundle.json" -o "output/kibana.yaml" --prefix-components-with-info-prop title